Desarrollo de complementos de Office

Sugerencia

Consulte Información general de la plataforma de complementos de Office antes de leer este artículo.

Todos los complementos de Office se crean en la plataforma de complementos de Office. Para la creación de cualquier complemento, tendrá que entender conceptos importantes, como la disponibilidad de plataforma y aplicación, los patrones de programación de la API de JavaScript de Office, cómo especificar la configuración y las características de un complemento en el archivo de manifiesto, cómo diseñar la IU y la experiencia de usuario y mucho más. Estos conceptos básicos de desarrollo se tratan en la sección Ciclo de vida de desarrollo>Desarrollo de la documentación. Revise la información que se muestra aquí antes de explorar la documentación específica de aplicación que se corresponde con el complemento que está creando (por ejemplo, Excel).

Crear un complemento para Office

Puede crear un complemento de Office mediante el generador de Yeoman para complementos de Office, Visual Studio o Teams Toolkit.

Generador de Yeoman

Puede usar el generador de Yeoman para complementos de Office con el fin de crear un proyecto de complemento de Node.js de Office que pueda administrar con Visual Studio Code u otro editor. El generador puede crear complementos de Office para cualquiera de los siguientes programas:

  • Excel
  • OneNote
  • Outlook
  • PowerPoint
  • Project
  • Word
  • Funciones personalizadas de Excel

Cree el proyecto con HTML, CSS y JavaScript (o TypeScript) o con React. Si elige React, también puede elegir entre JavaScript y Typescript. Para obtener más información sobre cómo crear complementos con el generador, consulte Generador de Yeoman para complementos de Office.

Visual Studio

Visual Studio se puede usar para crear complementos de Office para Excel, Outlook, Word y PowerPoint. Un proyecto de complemento de Office se crea como parte de una solución de Visual Studio y usa HTML, CSS y JavaScript. Para obtener más información sobre cómo crear complementos con Visual Studio, vea Desarrollar complementos de Office con Visual Studio.

Nota:

Aunque es posible crear complementos de Office con Visual Studio, usar el generador Yeoman ofrece una mejor experiencia para los desarrolladores de muchas maneras.

  • El generador Yeoman ofrece una variedad de opciones más amplia para los tipos de proyecto, marcos y lenguajes que las opciones de Visual Studio para proyectos de complementos de Office.

  • Las plantillas de proyecto del generador Yeoman se actualizan con más frecuencia que las plantillas de proyecto de Visual Studio.

Kit de herramientas de Teams

El kit de herramientas de Teams se puede usar para crear casi cualquier tipo de aplicación de Teams, un término que incluye todas las extensiones de Microsoft 365, incluidas las que no extienden la aplicación teams. Para obtener más información sobre cómo crear un complemento, consulte Creación de proyectos de complementos de Office con Teams Toolkit.

Información sobre las dos partes de un complemento de Office

Un complemento de Office consta de dos partes.

  • Manifiesto del complemento que define la configuración y las funcionalidades del complemento.

  • La aplicación web que define la interfaz de usuario y la funcionalidad de los componentes del complemento como paneles de tareas, complementos de contenido y cuadros de diálogo.

La aplicación web usa la API de JavaScript de Office para interactuar con el contenido del documento de Office en el que se ejecuta el complemento. El complemento también puede ejecutar funciones típicas de las aplicaciones web, como llamar a servicios web externos, facilitar la autenticación de usuarios y mucho más.

Definir la configuración y las funcionalidades de un complemento

El manifiesto de un complemento de Office define la configuración y las funcionalidades del complemento. En él, especificará cosas como:

  • Metadatos que describen el complemento (por ejemplo, ID., versión, descripción, nombre para mostrar, configuración regional predeterminada).
  • Las aplicaciones de Office en las que se ejecutará el complemento.
  • Permisos que necesita el complemento.
  • Cómo se integra el complemento con Office, incluida cualquier interfaz de usuario personalizada que cree el complemento (por ejemplo, una pestaña personalizada o botones personalizados de la cinta de opciones).
  • Ubicación de las imágenes que el complemento usa para la personalización de marca y la iconografía de los comandos.
  • Dimensiones del complemento (por ejemplo, dimensiones para complementos de contenido, altura solicitada para complementos de Outlook).
  • Reglas que especifican cuándo se activa el complemento en el contexto de un mensaje o una cita (solo para los complementos de Outlook).
  • Métodos abreviados de teclado (solo para Excel).

Para obtener información detallada sobre el manifiesto, vea Manifiesto de complementos de Office.

Interactuar con el contenido de un documento de Office

Un complemento de Office puede usar las API de JavaScript de Office para interactuar con el contenido del documento de Office donde se ejecuta el complemento.

Acceder a la biblioteca de API de JavaScript de Office

Se puede acceder a la biblioteca de la API de JavaScript de Office a través de la red de entrega de contenido (CDN) de Office JS en: https://appsforoffice.microsoft.com/lib/1/hosted/office.js. Para usar las API de JavaScript para Office en cualquiera de las páginas web del complemento, debe hacer referencia a la red CDN en una etiqueta <script> en la etiqueta <head> de la página.

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

Nota:

Para usar las API preliminares, haga referencia a la versión preliminar de la biblioteca de la API de JavaScript de Office en la red CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.

Para más información sobre cómo acceder a la biblioteca de API de JavaScript de Office, incluido cómo obtener la característica IntelliSense, consulte Hacer referencia a la biblioteca de la API de JavaScript de Office en la red de entrega de contenido (CDN).

Modelos de API

Las API de JavaScript para Office incluyen dos modelos distintos:

  • Las API específicas de aplicación proporcionan objetos fuertemente tipados que se pueden usar para interactuar con objetos nativos de una aplicación de Office específica. Por ejemplo, puede usar las API de JavaScript de Excel para acceder a hojas de cálculo, rangos, tablas y gráficos, entre otros. Las API específicas de la aplicación están disponibles actualmente para las siguientes aplicaciones de Office.

    Este modelo de API usa promesas y le permite especificar varias operaciones en cada solicitud que envíe a la aplicación de Office. Hacer operaciones por lotes de esta manera puede mejorar considerablemente el rendimiento de complementos en las aplicaciones de Office en la web. Las API específicas de la aplicación se introdujeron con Office 2016.

    Nota:

    También hay una API específica de la aplicación para Visio, pero solo puede usarla en páginas de SharePoint Online para interactuar con diagramas de Visio insertados en la página. Los complementos web de Office no se admiten en Visio.

    Para saber más sobre este modelo de API, consulte Uso del modelo de API específico de la aplicación.

  • Las API comunes se pueden usar para acceder a características como la interfaz de usuario, los cuadros de diálogo y la configuración del cliente, que son comunes a varios tipos de aplicaciones de Office. Este modelo de API usa devoluciones de llamadas, las cuales le permiten especificar solo una operación en cada solicitud enviada a la aplicación de Office. Las API comunes se introdujeron con Office 2013 y se pueden usar para interactuar con cualquier aplicación de Office compatible. Para más información sobre el modelo de objetos de API comunes, que incluye las API para interactuar con Outlook, PowerPoint y Project, consulte Modelo común de objetos de la API de JavaScript.

Nota:

Las funciones personalizadas sin un tiempo de ejecución compartido se ejecutan en un entorno de ejecución solo de JavaScript que prioriza la ejecución de cálculos. Estas funciones usan un modelo de programación ligeramente diferente.

Conjuntos de requisitos de la API

Los conjuntos de requisitos son grupos con nombres de miembros de la API. Los conjuntos de requisitos pueden ser específicos para las aplicaciones de Office, como, por ejemplo, el conjunto de requisitos de ExcelApi 1.7 (un conjunto de API que solo puede usarse en Excel), o comunes para varias aplicaciones, como el conjunto de requisitos de DialogApi 1.1 (un conjunto de API que se puede usar en cualquier aplicación de Office que admita una API de cuadro de diálogo).

El complemento puede usar conjuntos de requisitos para determinar si la aplicación de Office es compatible con los miembros de la API que necesita usar. Para obtener más información, vea Especificar requisitos de la API y aplicaciones de Office.

La compatibilidad del conjunto de requisitos varía en función de la plataforma, de la versión y de la aplicación de Office. Para obtener información detallada sobre las plataformas, los conjuntos de requisitos y las API comunes compatibles con cada aplicación de Office, vea Aplicación cliente de Office y disponibilidad de plataformas para complementos de Office.

Explorar las API con Script Lab

Script Lab es un complemento que le permite explorar la API de JavaScript para Office y ejecutar fragmentos de código mientras trabaja en un programa de Office como Excel o Word. Está disponible de forma gratuita mediante AppSource y es conveniente incluirlo en el kit de herramientas de desarrollo mientras crea el prototipo de su complemento y comprueba la funcionalidad que desea de él. En Script Lab puede tener acceso a una biblioteca de ejemplos integrados para probar rápidamente las API o incluso usar un ejemplo como punto de partida para su propio código.

El siguiente vídeo de un minuto muestra Script Lab en acción.

Vídeo corto que muestra Script Lab ejecutándose en Excel, Word y PowerPoint.

Para más información sobre Script Lab, consulte Explorar las API de JavaScript de Office con Script Lab.

Ampliar la interfaz de usuario de Office

Un complemento de Office puede ampliar la interfaz de usuario de Office con comandos de complemento y contenedores HTML, como paneles de tareas, complementos de contenido o cuadros de diálogo.

  • Los comandos de complementos se pueden usar para agregar una pestaña personalizada, botones y menús personalizados a la cinta predeterminada en Office, o para ampliar el menú contextual predeterminado que aparece cuando los usuarios hacen clic con el botón derecho en el texto de un documento de Office o en un objeto de Excel. Cuando los usuarios seleccionan un comando de complemento, inician la tarea que especifica el comando de complemento, como ejecutar código JavaScript, abrir un panel de tareas o iniciar un cuadro de diálogo.

  • Los contenedores HTML como paneles de tareas, complementos de contenidoy cuadros de diálogo pueden mostrar la interfaz de usuario personalizada y revelar funcionalidad adicional en una aplicación de Office. El contenido y la funcionalidad de cada panel de tareas, complemento de contenido o cuadro de diálogo se obtiene de una página web que especifique. Estas páginas web pueden usar la API de JavaScript de Office para interactuar con el contenido del documento de Office en el que se ejecuta el complemento y también pueden hacer otras tareas que suelen realizar las páginas web, como llamar a servicios web externos, facilitar la autenticación de usuarios y mucho más.

En la imagen siguiente se muestra un comando de complemento en la cinta de opciones, un panel de tareas a la derecha del documento y un cuadro de diálogo o un complemento de contenido sobre el documento.

Diagrama en el que se muestran los comandos de complemento en la cinta de opciones, un panel de tareas y un cuadro de diálogo o complemento de contenido de un documento de Office.

Para más información sobre cómo ampliar la interfaz de usuario de Office y diseñar la experiencia de usuario del complemento, vea Elementos de la interfaz de usuario de Office para complementos de Office.

Pasos siguientes

En este artículo se describen las diferentes formas de crear complementos para Office, se presentan diversas maneras en las que un complemento puede extender la IU de Office, se describen los conjuntos de API y se muestra cómo Scripts Lab es una herramienta valiosa para explorar las API de JavaScript para Office y realizar prototipos de funcionalidad de un complemento. Ahora que ha explorado esta información introductoria, puede continuar su trayecto con los complementos de Office de las siguientes maneras.

Crear un complemento para Office

Puede crear rápidamente un complemento básico para Excel, OneNote, Outlook, PowerPoint, Project o Word siguiendo el inicio rápido de 5 minutos. Si ya ha completado el inicio rápido y desea crear un complemento algo más elaborado, pruebe a usar el tutorial.

Más información

Infórmese del desarrollo, las pruebas y la publicación de complementos para Office explorando esta documentación.

Sugerencia

Para los complementos que cree, tiene información en la sección Ciclo de vida del desarrollo de esta documentación, además de la información en la sección específica de la aplicación que se corresponda con el tipo de complemento que cree (por ejemplo, Excel).

Consulte también