Paneles de tareas y configuración persistente
En esta unidad, aprenderá a usar paneles de tareas en complementos de Outlook y a almacenar la configuración de usuario para su uso en todos los dispositivos.
Panel de tareas anclable
De forma predeterminada, si un usuario tiene un panel de tareas de complemento abierto para un mensaje en el panel de lectura y, a continuación, selecciona un nuevo mensaje, el panel de tareas se cierra automáticamente. El anclaje permite que el panel de tareas permanezca activado.
Los paneles de tareas anclables son ideales para complementos muy usados. En estos casos, el usuario puede preferir mantener ese panel abierto, lo que elimina la necesidad de reactivar el complemento en cada mensaje.
Nota:
Actualmente, los paneles de tareas anclables solo están disponibles para los suscriptores de Microsoft 365 mediante lo siguiente:
- Outlook 2016 o posterior en Windows (compilación 7668.2000 o posterior para los usuarios del canal Actual u Office Insider, compilación 7900.xxxx o posterior para usuarios en el canal Diferido)
- Outlook 2016 o posterior en Mac (versión 16.13.503 o posterior)
- Outlook en la Web (versión moderna)
Los desarrolladores deben especificar en el manifiesto que el panel de tareas admite el anclaje y la "escucha" de nuevas selecciones de elementos para actualizar la interfaz de usuario del panel de tareas.
Implementar un panel de tareas anclable
Para implementar un panel de tareas anclable, agregue el elemento SupportsPinning al manifiesto del complemento:
<Action xsi:type="ShowTaskpane">
<SourceLocation resid="readTaskPaneUrl" />
<SupportsPinning>true</SupportsPinning>
</Action>
// Set up ItemChanged event to listen for new item selections in Outlook
Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, function(eventArgs) {
// Update UI based on the new current item...this should check for null item
});
También tendrás que implementar un controlador para el evento ItemChanged para que el complemento pueda actualizar la interfaz de usuario cuando se seleccione un nuevo elemento.
El controlador de ItemChanged debe tener en cuenta null porque el usuario no podría tener ninguna selección, lo que devolvería un elemento null.
Office.js para complementos de correo
Echemos un vistazo a algunas tareas comunes a las que se enfrentan los desarrolladores al crear complementos para Outlook con Office.js.
Escribir en el cuerpo del mensaje
En el ejemplo siguiente se muestran algunas operaciones básicas del cuerpo del mensaje. El método body.getAsync() se usa para leer el cuerpo de un mensaje. Observe el tipo de conversión que se especifica. En este ejemplo, se solicita que el contenido se devuelva como HTML.
Antes de insertar datos en el cuerpo del mensaje, debe comprobar el formato del mensaje mediante el método body.getTypeAsync().
En el ejemplo se muestra la inserción de datos en dos lugares diferentes del mensaje:
- la posición del cursor actual
- el principio del cuerpo
// Get item body
item.body.getAsync(coercionType: Office.CoercionType.Html, function (asyncResult) {
// asyncResult.value;
}
// Insert data in item body
item.body.getTypeAsync(function (r) { // check the format of the message body
if (r.status != Office.AsyncResultStatus.Failed && r.value == Office.MailboxEnums.BodyType.Html) {
// Insert data at the current cursor position
item.body.setSelectedDataAsync("<b>Hello!</b>", { coercionType: Office.CoercionType.Html,
asyncContext: { var3: 1, var4: 2 } }, function (asyncResult) {
});
// Insert data at the beginning of the item body
item.body.prependAsync("<b>Hello!</b>", { coercionType: Office.CoercionType.Html,
asyncContext: { var3: 1, var4: 2 } }, function (asyncResult) {
});
...
Obtener o establecer destinatarios de mensajes y citas
En el ejemplo siguiente se muestra cómo obtener y establecer los destinatarios para mensajes y citas.
El método de uso getAsync() es principalmente para complementos de redacción. Los complementos de lectura tienen acceso directo a los destinatarios mediante las propiedades item.to, item.ccy item.bcc.
Cada destinatario se establece mediante una matriz de objetos, donde cada objeto tiene una propiedad displayName y emailAddress.
// Get recipients
const item = Office.context.mailbox.item;
let toRecipients;
if (item.itemType == Office.MailboxEnums.ItemType.Appointment) // Handle appointment vs message
toRecipients = item.requiredAttendees;
else
toRecipients = item.to;
// Perform the async get (compose add-in…read add-in can simply call item.to)
toRecipients.getAsync(function (asyncResult) { };
// Perform the async set
toRecipients.setAsync(
[
{
"displayName":"Graham Durkin",
"emailAddress":"graham@contoso.com"
},{
"displayName" : "Donnie Weinberg",
"emailAddress" : "donnie@contoso.com"
}
], function (r) {
// check status.
});
Nota:
En el ejemplo se examinan los asistentes y destinatarios necesarios en el campo Para; sin embargo, también funciona para asistentes y destinatarios opcionales en los campos CC y CCO.
Obtener o establecer la periodicidad
En este ejemplo se muestra cómo establecer una configuración de periodicidad de cita, que es un objeto más complejo mediante el objeto SeriesTime.
// Get and set recurrence
const seriesTimeObject = new Office.SeriesTime();
seriesTimeObject.setStartDate(2019,10,2);
seriesTimeObject.setEndDate(2019,11,2);
seriesTimeObject.setStartTime(10,30);
seriesTimeObject.setDuration(30);
const pattern = {
"seriesTime": seriesTimeObject,
"recurrenceType": "weekly",
"recurrenceProperties": {"interval": 1, "days": ["tue", "thu"]},
"recurrenceTimeZone": {"name": "Pacific Standard Time"}};
// Set recurrence
Office.context.mailbox.item.recurrence.setAsync(pattern, function(asyncResult) { .. });
// Get recurrence
Office.context.mailbox.item.recurrence.getAsync(function(asyncResult) { .. });
Configuración de movilidad
La configuración de itinerancia es una herramienta valiosa para que un complemento guarde información configurable que se almacena en el servidor de correo y está disponible en cualquier dispositivo.
En el ejemplo siguiente se muestra cómo obtener, establecer y quitar la configuración de itinerancia de un usuario.
// Roaming Settings
Office.initialize = function () {
const settings = Office.context.roamingSettings;
// Save roaming settings for the mailbox to the server so always available
settings.set("cookie", Date());
settings.saveAsync(function(asyncResult) {});
// Remove a roaming setting
settings.remove("cookie");
settings.saveAsync(function(asyncResult) {});
// Get roaming setting
const val = settings.get("cookie");
}
Tokens y API (servicios Web Exchange)
En este ejemplo se muestra cómo llamar a los servicios web de Exchange (EWS) desde un complemento mediante Office.js.
// Call Exchange Web Services (EWS)
const mailbox = Office.context.mailbox;
mailbox.makeEwsRequestAsync(mailbox.item.itemId, function(result) {
// result.value contains the EWS getItem information in XML format
const response = $.parseXML(result.value);
const extendedProps = response.getElementsByTagName("ExtendedProperty")
});
// Note add-ins calling EWS must be installed by an Exchange admin
Nota:
Para llamar a EWS desde un complemento, un administrador de Exchange debe instalar el complemento y debe analizar todo el XML enviado y recibido de EWS en el complemento.
Obtener datos adjuntos
En el ejemplo siguiente se muestra cómo obtener datos adjuntos mediante Office.js.
Los complementos de Outlook no pueden pasar los datos adjuntos de un elemento seleccionado directamente desde el cliente. En su lugar, Outlook puede devolver un token de acceso de OAuth 2.0 que el complemento puede usar para llamar a las API de REST de Outlook.
// Get attachments
const svcRequest = { attachmentToken: '', ewsUrl: Office.context.mailbox.ewsUrl, attachments: [] };
Office.context.mailbox.getCallbackTokenAsync(function(asyncResult, userContext) {
// get access token returned from getCallbackTokenAsync and capture attachment metadata
svcRequest.attachmentToken = asyncResult.value;
for (let i = 0; i < mailbox.item.attachments.length; i++) {
svcRequest.attachments[i] = JSON.parse(JSON.stringify(mailbox.item.attachments[i].$0_0));
}
$.ajax({
url: './api/YourApiFprProcessingAttachments',
type: 'POST',
data: JSON.stringify(svcRequest), // contains metadata on all attachments and access token
contentType: 'application/json;charset=utf-8'
})
});
Agregar o eliminar datos adjuntos
En el ejemplo siguiente se muestra cómo agregar y quitar datos adjuntos de un elemento de Outlook.
// Attach a file
Office.context.mailbox.item.addFileAttachmentAsync(
'https://webserver/picture.png',
'picture.png', { asyncContext: null }, function (asyncResult) {
// Validate status asyncResult.status
}
);
// Attach an Outlook item
Office.context.mailbox.item.addItemAttachmentAsync(
itemId,
'Welcome message', { asyncContext: null }, function (asyncResult) {
// Validate status asyncResult.status
}
);
// Remote an attachment
Office.context.mailbox.item.removeAttachmentAsync(
attachmentId,
{ asyncContext: null }, function (asyncResult) {
// Validate status asyncResult.status
}
);
Resumen
En esta unidad, aprenderá a usar paneles de tareas en complementos de Outlook y a almacenar la configuración de usuario para su uso en todos los dispositivos.