API de complemento de Outlook

  • Artículo

Para usar las API en el complemento de Outlook, debe especificar la ubicación de la biblioteca Office.js, el conjunto de requisitos, el esquema y los permisos. Usará principalmente las API de JavaScript de Office expuestas a través del objeto Mailbox .

Biblioteca Office.js

Para interactuar con la API del complemento de Outlook, debe usar las API de JavaScript en Office.js. La red de entrega de contenido (CDN) de la biblioteca es https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Los complementos que se envían a AppSource deben hacer referencia a Office.js por medio de esta CDN. No pueden usar una referencia local.

Haga referencia a la CDN en una etiqueta <script> de la etiqueta <head> de la página web (archivo .html, .aspx o .php) que implemente la interfaz de usuario del complemento.

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

A medida que agregamos nuevas API, la dirección URL de Office.js seguirá siendo la misma. Cambiaremos la versión en la dirección URL solo si se interrumpe un comportamiento existente de la API.

Importante

Al desarrollar un complemento para cualquier aplicación cliente de Office, haga referencia a la API de JavaScript de Office desde dentro de la <head> sección de la página. Esto garantiza que la API se inicialice por completo antes de los elementos del cuerpo.

Conjuntos de requisitos

Todas las API de Outlook pertenecen al conjunto de requisitos de buzón. El conjunto de requisitos Mailbox tiene versiones y cada nuevo conjunto de API que se publica pertenece a una versión posterior del conjunto. No todos los clientes de Outlook admitirán el conjunto más reciente de API cuando se publique, pero si un cliente de Outlook declara la compatibilidad con un conjunto de requisitos, será compatible con todas las API de ese conjunto de requisitos.

Para controlar los clientes de Outlook donde aparece el complemento, especifique una versión mínima de conjunto de requisitos en el manifiesto. Por ejemplo, si especifica la versión 1.3 del conjunto de requisitos, el complemento no se mostrará en los clientes de Outlook que no sean compatibles con una versión mínima de 1.3.

Especificar un requisito no limita el complemento a las API de esa versión. Si en el complemento se especifica como conjunto de requisitos la versión 1.1, pero se ejecuta en un cliente que es compatible con la versión 1.3, el complemento puede usar las API de la versión 1.3. El conjunto de requisitos solo controla los clientes de Outlook donde se mostrará el complemento.

Para comprobar la disponibilidad de las API de un conjunto de requisitos superior al especificado en el manifiesto, puede usar la técnica de JavaScript estándar:

if (item.somePropertyOrFunction) {
   item.somePropertyOrFunction...  
}

Nota:

Estas comprobaciones son necesarias para cualquier API que esté en la versión del conjunto de requisitos especificada en el manifiesto.

Especifique el conjunto de requisitos mínimo compatible con el conjunto fundamental de API para su escenario, sin el que no funcionarán las características del complemento. Especifique el conjunto de requisitos en el manifiesto. El marcado varía en función del manifiesto que use.

  • Manifiesto XML: use el <elemento Requirements> . Tenga en cuenta que el <elemento secundario Methods> de <Requirements> no se admite en los complementos de Outlook, por lo que no puede declarar la compatibilidad con métodos específicos.
  • Manifiesto unificado para Microsoft 365: use la propiedad "extensions.capabilities".

Para obtener más información, vea Manifiestos de complementos de Office y Descripción de los conjuntos de requisitos de la API de Outlook.

Permissions

El complemento necesita los permisos adecuados para usar las API que necesita. En general, tiene que especificar el permiso mínimo necesario para el complemento.

Hay cuatro niveles de permisos; restringido, elemento de lectura, elemento de lectura y escritura y buzón de lectura y escritura. Para obtener más información. Para más información, vea Información sobre los permisos del complemento de Outlook.

Objeto Mailbox

Los complementos de Outlook usan, principalmente, un subconjunto de la API que se expone a través del objeto Mailbox. Para tener acceso a los objetos y miembros específicamente para su uso en complementos de Outlook, como el objeto Item , use la propiedad mailbox del objeto Context para acceder al objeto Mailbox , como se muestra en la siguiente línea de código.

// Access the Item object.
const item = Office.context.mailbox.item;

Además, los complementos de Outlook pueden usar los siguientes objetos.

  • Objeto de Office: para inicialización.

  • Objeto Context: para obtener acceso al contenido y para mostrar las propiedades de idioma.

  • Objeto RoamingSettings: para guardar configuraciones personalizadas específicas del complemento de Outlook en el buzón del usuario donde está instalado el complemento.

Para obtener información sobre el uso de JavaScript en los complementos de Outlook, consulte Complementos de Office.

Consulte también