Información sobre la API de JavaScript para OfficeUnderstanding the JavaScript API for Office

Este artículo proporciona información acerca de la API de JavaScript para Office y cómo usarla. Para obtener información de referencia, consulte API de JavaScript para Office. Para obtener información sobre cómo actualizar los archivos de proyecto de Visual Studio a la versión más reciente de la API de JavaScript para Office, consulte Actualizar la versión de la API de JavaScript para Office y los archivos de esquema de manifiesto.This article provides information about the JavaScript API for Office and how to use it. For reference information, see JavaScript API for Office. For information about updating Visual Studio project files to the most current version of the JavaScript API for Office, see Update the version of your JavaScript API for Office and manifest schema files.

Nota

Si tiene previsto publicar el complemento en AppSource y que esté disponible en la experiencia de Office, asegúrese de que se ajusta a las directivas de validación de AppSource. Por ejemplo, para superar la validación, el complemento debe funcionar en todas las plataformas que sean compatibles con los métodos especificados (para más información, consulte la sección 4.12 y el host del complemento de Office y la página de disponibilidad).If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Referencia a la biblioteca de la API de Javascript para Office en el complementoReferencing the JavaScript API for Office library in your add-in

La biblioteca de la API de JavaScript para Office está formada por el archivo Office.js y los archivos .js específicos de la aplicación host asociada, como Excel-15.js y Outlook-15.js. El método más sencillo para hacer referencia a la API es usar nuestra CDN. Para hacerlo, agregue el siguiente <script> a la etiqueta <head> de la página:The JavaScript API for Office library consists of the Office.js file and associated host application-specific .js files, such as Excel-15.js and Outlook-15.js. The simplest method of referencing the API is using our CDN by adding the following <script> to your page's <head> tag:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

Esto descargará y almacenará en caché los archivos de la API de JavaScript para Office la primera vez que se cargue el complemento para asegurarse de que usa la implementación más actualizada de Office.js y de sus archivos asociados para la versión especificada.This will download and cache the JavaScript API for Office files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Para más información sobre la CDN de Office.js, incluido cómo se administra el control de versiones y la compatibilidad con versiones anteriores, vea Referencia a la biblioteca de la API de Javascript para Office desde su red de entrega de contenido (CDN).For more details around the Office.js CDN, including how versioning and backward compatibility is handled, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Inicializar el complementoInitializing your add-in

Se aplica a: todos los tipos de complementosApplies to: All add-in types

Los complementos de Office suelen incluir lógica de inicio para realizar acciones como:Office Add-ins often have start-up logic to do things such as:

  • Compruebe que la versión del usuario de Office admitirá todas las API de Office a las que llama el código.Check that the user's version of Office will support all the Office APIs that your code calls.

  • Asegúrese de que existen determinados objetos, como la hoja de cálculo con un nombre específico.Ensure the existence of certain artifacts, such as worksheet with a specific name.

  • Pide al usuario que seleccione algunas celdas en Excel y, a continuación, inserta un gráfico inicializado con los valores seleccionados.Prompting the user to select some cells in Excel, and then inserting a chart initialized with those selected values.

  • Establecer enlaces.Establish bindings.

  • Use la API de cuadro de diálogo de Office para preguntar al usuario los valores de configuración predeterminados del complemento.Use the Office dialog API to prompt the user for default add-in settings values.

Pero el código de inicio no debe llamar a ninguna API de Office.js hasta que la biblioteca esté cargada.But your start-up code must not call any Office.js APIs until the library is loaded. Hay dos formas por las que el código puede asegurarse de que se ha cargado la biblioteca.There are two ways that your code can ensure that the library is loaded. Se describen en las secciones siguientes:They are described in the following sections:

Sugerencia

Le recomendamos que use Office.onReady() en lugar de Office.initialize.We recommend that you use Office.onReady() instead of Office.initialize. Aunque Office.initialize todavía es compatible, usar Office.onReady() ofrece más flexibilidad.Although Office.initialize is still supported, using Office.onReady() provides more flexibility. Puede asignar solo un controlador a Office.initialize y infraestructura de Office lo llamará, una sola vez; pero puede llamar a Office.onReady() en lugares diferentes en el código y usar diferentes devoluciones de llamada.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure, but you can call Office.onReady() in different places in your code and use different callbacks.

Para obtener información sobre las diferencias entre estas técnicas, vea Principales diferencias entre Office.initialize y Office.onReady().For information about the differences in these techniques, see Major differences between Office.initialize and 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.For more details about the sequence of events when an add-in is initialized, see Loading the DOM and runtime environment.

Inicializar con Office.onReady()Initialize with Office.onReady()

Office.onReady() es un método asincrónico que devuelve un objeto Promise mientras comprueba si la biblioteca Office.js está totalmente cargada.Office.onReady() is an asynchronous method that returns a Promise object while it checks to see if the Office.js library is loaded. Cuando, y solo cuando, se ha cargado la biblioteca, se resuelve la promesa como un objeto que especifica la aplicación host 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.).When the library is loaded, it resolves the Promise as an object that specifies the Office host application with an Office.HostType enum value (Excel, Word, etc.) and the platform with an Office.PlatformType enum value (PC, Mac, OfficeOnline, etc.). El objeto Promise se resuelve inmediatamente si la biblioteca ya se ha cargado al llamar a Office.onReady().The Promise resolves immediately if the library is already loaded when Office.onReady() is called.

Una forma de llamar a Office.onReady() es pasar un método de devolución de llamada.One way to call Office.onReady() is to pass it a callback method. Aquí le mostramos un ejemplo:Here's an example:

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.Alternatively, you can chain a then() method to the call of Office.onReady(), instead of passing a callback. 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.For example, the following code checks to see that the user's version of Excel supports all the APIs that the add-in might call.

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 palabras clave async y await en TypeScript:Here is the same example using the async and await keywords in 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 o sus propias pruebas de inicialización, normalmente tiene que colocarlos dentro de la respuesta a Office.onReady().If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the response to Office.onReady(). Por ejemplo, se hará referencia a la función $(document).ready() de jQuery de esta forma:For example, JQuery's $(document).ready() function would be referenced as follows:

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

Sin embargo, hay excepciones para este procedimiento.However, there are exceptions to this practice. Por ejemplo, suponga que desea abrir el complemento en un explorador (en lugar de transferirlo a un host de Office) para depurar su interfaz de usuario con las herramientas del explorador.For example, suppose you want to open your add-in in a browser (instead of sideload it in an Office host) in order to debug your UI with browser tools. Puesto que Office.js no se carga en el explorador, onReady no se ejecutará y $(document).ready no se ejecutará si se llama dentro de onReady de Office.Since Office.js won't load in the browser, onReady won't run and the $(document).ready won't run if it's called inside the Office onReady. Otra excepción: desea que un indicador de progreso aparezca en el panel de tareas mientras el complemento se carga.Another exception: you want a progress indicator to appear in the task pane while the add-in is loading. En este escenario, el código debería llamar a la jQuery ready y utilizar su devolución de llamada para representar el indicador de progreso.In this scenario, your code should call the jQuery ready and use it's callback to render the progress indicator. Entonces la devolución de llamada onReady de Office puede reemplazar el indicador de progreso con la interfaz de usuario final.Then the Office onReady's callback can replace the progress indicator with the final UI.

Inicializar con Office.initializeInitialize with Office.initialize

Cuando la biblioteca Office.js está cargada y lista para la interacción del usuario, se desencadena un evento de inicialización.An initialize event fires when the Office.js library is loaded and ready for user interaction. Puede asignar un controlador a Office.initialize que implementa la lógica de inicialización.You can assign a handler to Office.initialize that implements your initialization logic. 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.The following is an example that checks to see that the user's version of Excel supports all the APIs that the add-in might call.

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 o sus propias pruebas de inicialización, normalmente tiene que colocarlos dentro del evento Office.initialize.If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the Office.initialize event. (Pero las excepciones que se describen en la sección Inicializar con Office.onReady() anteriormente también se aplican en este caso.) Por ejemplo, se haría referencia a la función $(document).ready() de JQuery de la siguiente forma:(But the exceptions described in the Initialize with Office.onReady() section earlier apply in this case also.) For example, JQuery's $(document).ready() function would be referenced as follows:

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.For task pane and content add-ins, Office.initialize provides an additional reason parameter. Este parámetro determina cómo se agregó un complemento al documento actual.This parameter specifies how an add-in was added to the current document. 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.You can use this to provide different logic for when an add-in is first inserted versus when it already existed within the document.

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.For more information, see Office.initialize Event and InitializationReason Enumeration.

Principales diferencias entre Office.initialize y Office.onReadyMajor differences between Office.initialize and 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.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure; but you can call Office.onReady() in different places in your code and use different callbacks. 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.For example, your code could call Office.onReady() as soon as your custom script loads with a callback that runs initialization logic; and your code could also have a button in the task pane, whose script calls Office.onReady() with a different callback. Si es así, se ejecuta la segunda llamada al hacer clic en el botón.If so, the second callback runs when the button is clicked.

  • El evento Office.initialize se activa al final del proceso interno en el que Office.js se inicializa.The Office.initialize event fires at the end of the internal process in which Office.js initializes itself. Y se activa inmediatamente tras la finalización del proceso interno.And it fires immediately after the internal process ends. 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.If the code in which you assign a handler to the event executes too long after the event fires, then your handler doesn't run. 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.For example, if you are using the WebPack task manager, it might configure the add-in's home page to load polyfill files after it loads Office.js but before it loads your custom JavaScript. Cuando el script termina de cargarse y asignar el controlador, ya ha ocurrido el evento de inicialización.By the time your script loads and assigns the handler, the initialize event has already happened. Pero nunca es "demasiado tarde" para llamar a Office.onReady().But it is never "too late" to call Office.onReady(). Si ya ha ocurrido el evento de inicialización, la devolución de llamada se ejecuta inmediatamente.If the initialize event has already happened, the callback runs immediately.

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.Even if you have no start-up logic, you should either call Office.onReady() or assign an empty function to Office.initialize when your add-in JavaScript loads. Algunas combinaciones de plataforma y host de Office no cargan el panel de tareas hasta que se produce una de las siguientes.Some Office host and platform combinations won't load the task pane until one of these happens. Los siguientes ejemplos muestran estos dos métodos.The following examples show these two approaches.

Office.onReady();
Office.initialize = function () {};

Modelo de objetos de la API de JavaScript de OfficeOffice JavaScript API object model

Una vez inicializado, el complemento puede interactuar con el host (por ejemplo, Excel o Outlook).Once initialized, the add-in can interact with the host (e.g. Excel, Outlook). La página modelo de objetos de la API de JavaScript de Office tiene más información sobre los patrones de uso específicos.The Office JavaScript API object model page has more details on specific usage patterns. También hay documentación de referencia detallada para las API comunes y las API de hosts específicos.There is also detailed reference documentation for both Common APIs and host-specific APIs.