Compartir a través de

Administrar los datos adjuntos de un elemento en un formulario de redacción en Outlook

  • Artículo

La API de JavaScript de Office proporciona varias API para administrar los datos adjuntos de un elemento cuando el usuario está redactando un mensaje o una cita.

Adjuntar un archivo o un elemento de Outlook

Adjunte un archivo o un elemento de Outlook a un formulario de redacción mediante el método adecuado para el tipo de datos adjuntos.

Estos son métodos asincrónicos, lo que significa que la ejecución puede continuar sin esperar a que se complete la acción. En función de la ubicación original y el tamaño de los datos adjuntos que se van a agregar, la llamada asincrónica puede tardar un tiempo en completarse.

Si hay tareas que dependen de la acción que se va a completar, debe realizar esas tareas en una función de devolución de llamada. Esta función de devolución de llamada es opcional y se invoca cuando se ha completado la carga de datos adjuntos. La función de devolución de llamada toma un objeto AsyncResult como parámetro de salida que proporciona cualquier estado, error y valor devuelto al agregar los datos adjuntos. Si la devolución de llamada requiere parámetros adicionales, puede especificarlos en el parámetro opcional options.asyncContext. options.asyncContext puede ser de cualquier tipo que la función de devolución de llamada espera.

Por ejemplo, puede definir options.asyncContext como un objeto JSON que contiene uno o varios pares clave-valor. Para obtener más ejemplos sobre cómo pasar parámetros opcionales a métodos asincrónicos en la plataforma de complementos de Office, vea Programación asincrónica en complementos de Office. En el ejemplo siguiente se muestra cómo usar el asyncContext parámetro para pasar dos argumentos a una función de devolución de llamada.

const options = { asyncContext: { var1: 1, var2: 2 } };

Office.context.mailbox.item.addFileAttachmentAsync("https://contoso.com/rtm/icon.png", "icon.png", options, callback);

Para comprobar el resultado de una llamada al método asincrónico en la función de devolución de llamada, use las status propiedades y error del AsyncResult objeto . Si la asociación se completa correctamente, use la AsyncResult.value propiedad para obtener el identificador de datos adjuntos. Este identificador es un número entero que podrá usar posteriormente para quitar los datos adjuntos.

Nota:

El identificador de datos adjuntos solo es válido dentro de la misma sesión y no se garantiza que se asigne a los mismos datos adjuntos entre sesiones. Los ejemplos de cuando una sesión ha terminado incluyen cuando el usuario cierra el complemento, o si el usuario comienza a redactar en un formulario insertado y, posteriormente, extrae el formulario insertado para continuar en una ventana independiente.

Sugerencia

Hay límites a los archivos o elementos de Outlook que puede adjuntar a un elemento de correo, como el número de datos adjuntos y su tamaño. Para obtener más instrucciones, consulte Límites para la API de JavaScript.

Adjuntar un archivo

Puede adjuntar un archivo a un mensaje o cita en un formulario de redacción mediante el addFileAttachmentAsync método y especificando el URI del archivo. También puede usar el addFileAttachmentFromBase64Async método , especificando la cadena codificada en Base64 como entrada. Si el archivo está protegido, puede incluir un token de autenticación o identidad apropiado como parámetro de cadena de consulta de URI. Exchange realizará una llamada al URI para obtener los datos adjuntos y el servicio web que protege el archivo tendrá que usar el token como forma de autenticación.

Nota:

El URI del archivo que se va a adjuntar debe admitir el almacenamiento en caché en producción. El servidor que hospeda la imagen no debe devolver un Cache-Control encabezado que especifique no-cache, no-storeo opciones similares en la respuesta HTTP. Sin embargo, al desarrollar el complemento y realizar cambios en los archivos, el almacenamiento en caché puede impedir que vea los cambios. Se recomienda usar Cache-Control encabezados durante el desarrollo.

El siguiente ejemplo de JavaScript es un complemento de redacción que adjunta un archivo, picture.png, de un servidor web al mensaje o cita que se está redactando. La función de devolución de llamada toma asyncResult como parámetro, comprueba el estado del resultado y obtiene el identificador de datos adjuntos si el método se realiza correctamente.

// Add the specified file attachment to the item
// being composed.
// When the attachment finishes uploading, the
// callback function is invoked and gets the attachment ID.
// You can optionally pass any object that you would
// access in the callback function as an argument to
// the asyncContext parameter.
Office.context.mailbox.item.addFileAttachmentAsync(
    "https://webserver/picture.png",
    "picture.png",
    { asyncContext: { var1: 1, var2: 2 } },
    (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.error(asyncResult.error.message);
            return;
        }

        // Get the ID of the attached file.
        const attachmentID = asyncResult.value;
        console.log(`ID of added attachment: ${attachmentID}`);
    }
);

Para agregar una imagen codificada en Base64 al cuerpo de un mensaje o cita que se va a componer, primero debe obtener el cuerpo del elemento actual mediante el Office.context.mailbox.item.body.getAsync método antes de insertar la imagen mediante el addFileAttachmentFromBase64Async método . De lo contrario, la imagen no se representará en el cuerpo una vez insertada. Para obtener instrucciones, vea el siguiente ejemplo de JavaScript, que agrega una imagen Base64 insertada al principio de un cuerpo de elemento.

const mailItem = Office.context.mailbox.item;
const base64String =
  "iVBORw0KGgoAAAANSUhEUgAAAGAAAABgCAMAAADVRocKAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAnUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN0S+bUAAAAMdFJOUwAQIDBAUI+fr7/P7yEupu8AAAAJcEhZcwAADsMAAA7DAcdvqGQAAAF8SURBVGhD7dfLdoMwDEVR6Cspzf9/b20QYOthS5Zn0Z2kVdY6O2WULrFYLBaLxd5ur4mDZD14b8ogWS/dtxV+dmx9ysA2QUj9TQRWv5D7HyKwuIW9n0vc8tkpHP0W4BOg3wQ8wtlvA+PC1e8Ao8Ld7wFjQtHvAiNC2e8DdqHqKwCrUPc1gE1AfRVgEXBfB+gF0lcCWoH2tYBOYPpqQCNwfT3QF9i+AegJfN8CtAWhbwJagtS3AbIg9o2AJMh9M5C+SVGBvx6zAfmT0r+Bv8JMwP4kyFPir+cswF5KL3WLv14zAFBCLf56Tw9cparFX4upgaJUtPhrOS1QlY5W+vWTXrGgBFB/b72ev3/0igUdQPppP/nfowfKUUEFcP207y/yxKmgAYQ+PywoAFOfCH3A2MdCFzD3kdADBvq10AGG+pXQBgb7pdAEhvuF0AIc/VtoAK7+JciAs38KIuDugyAC/v4hiMCE/i7IwLRBsh68N2WQjMVisVgs9i5bln8LGScNcCrONQAAAABJRU5ErkJggg==";

// Get the current body of the message or appointment.
mailItem.body.getAsync(Office.CoercionType.Html, (bodyResult) => {
    if (bodyResult.status === Office.AsyncResultStatus.Failed) {
        console.error(bodyResult.error.message);
        return;
    }

    // Insert the Base64-encoded image at the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
        if (attachResult.status === Office.AsyncResultStatus.Failed) {
            console.error(attachResult.error.message);
            return;
        }

        let body = attachResult.asyncContext;
        body = body.replace("<p class=MsoNormal>", `<p class=MsoNormal><img src="cid:sample.png">`);
        mailItem.body.setAsync(body, { coercionType: Office.CoercionType.Html }, (setResult) => {
            if (setResult.status === Office.AsyncResultStatus.Failed) {
                console.error(setResult.error.message);
                return;
            }

            console.log("Inline Base64 image added to the body.");
        });
    });
});

Adjuntar un elemento de Outlook

Para adjuntar un elemento de Outlook (por ejemplo, correo electrónico, calendario o elemento de contacto) a un mensaje o cita en un formulario de redacción, especifique el identificador de Exchange Web Services (EWS) del elemento y use el addItemAttachmentAsync método . Para obtener el identificador de EWS del elemento, use la propiedad item.itemId .

La siguiente función de JavaScript, addItemAttachment, extiende un ejemplo anterior y agrega un elemento como datos adjuntos al correo electrónico o la cita que se está redactando. La función toma el identificador de EWS del elemento que se va a adjuntar como argumento. Si la asociación se realiza correctamente, obtiene el identificador de datos adjuntos para su posterior procesamiento.

// Adds the specified item as an attachment to the composed item.
// ID is the EWS ID of the item to be attached.
function addItemAttachment(itemId) {
    // When the attachment finishes uploading, the
    // callback function is invoked. Here, the callback
    // function uses only asyncResult as a parameter,
    // and if the attaching succeeds, gets the attachment ID.
    // You can optionally pass any other object you wish to
    // access in the callback function as an argument to
    // the asyncContext parameter.
    Office.context.mailbox.item.addItemAttachmentAsync(
        itemId,
        "Welcome email",
        { asyncContext: { var1: 1, var2: 2 } },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            const attachmentID = asyncResult.value;
            console.log(`ID of added attachment: ${attachmentID}`);
        }
    );
}

Nota:

Puede usar un complemento de redacción para adjuntar una instancia de una cita periódica en Outlook en la Web, en dispositivos móviles o en nueva Outlook en Windows. Sin embargo, en un cliente auxiliar de Outlook en Windows o en Mac, si se intenta adjuntar una instancia, se adjuntaría la serie periódica (la cita primaria).

Obtener datos adjuntos

Las siguientes API para obtener datos adjuntos en modo de redacción están disponibles en el conjunto de requisitos 1.8.

Use el método getAttachmentsAsync para obtener los datos adjuntos del mensaje o cita que se está redactando.

Para obtener el contenido de un archivo adjunto, use el método getAttachmentContentAsync . Los formatos admitidos aparecen en la enumeración AttachmentContentFormat .

Debe proporcionar una función de devolución de llamada para comprobar el estado y cualquier error mediante el objeto de AsyncResult parámetro de salida. También puede pasar parámetros adicionales a la función de devolución de llamada mediante el parámetro opcional asyncContext .

En el siguiente ejemplo de JavaScript se obtienen los datos adjuntos y se permite configurar un control distinto para cada formato de datos adjuntos admitido.

const item = Office.context.mailbox.item;
const options = { asyncContext: { currentItem: item } };
item.getAttachmentsAsync(options, callback);

function callback(result) {
  if (result.value.length > 0) {
    for (let i = 0 ; i < result.value.length ; i++) {
      result.asyncContext.currentItem.getAttachmentContentAsync(result.value[i].id, handleAttachmentsCallback);
    }
  }
}

function handleAttachmentsCallback(result) {
  // Parse string to be a url, an .eml file, a Base64-encoded string, or an .icalendar file.
  switch (result.value.format) {
    case Office.MailboxEnums.AttachmentContentFormat.Base64:
      // Handle file attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.Eml:
      // Handle email item attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.ICalendar:
      // Handle .icalender attachment.
      break;
    case Office.MailboxEnums.AttachmentContentFormat.Url:
      // Handle cloud attachment.
      break;
    default:
      // Handle attachment formats that are not supported.
  }
}

Sugerencia

Si el cliente de Outlook en el que se ejecuta el complemento no admite el conjunto de requisitos de buzón 1.8, puede obtener los datos adjuntos y su contenido de un elemento que se compone mediante Microsoft Graph o EWS. Para obtener más información, vea Obtener datos adjuntos de un elemento de Outlook de Exchange.

Eliminación de datos adjuntos

Para quitar un archivo o un elemento adjunto de un mensaje o elemento de cita en un formulario de redacción, especifique el identificador de datos adjuntos correspondiente en el método removeAttachmentAsync .

Importante

Si usa el conjunto de requisitos 1.7 o anterior, solo debe quitar los datos adjuntos que el mismo complemento ha agregado en la misma sesión.

De forma similar a los addFileAttachmentAsyncmétodos , addItemAttachmentAsyncy getAttachmentsAsync , removeAttachmentAsync es un método asincrónico. Debe proporcionar una función de devolución de llamada para comprobar el estado y cualquier error mediante el objeto de AsyncResult parámetro de salida. También puede pasar parámetros adicionales a la función de devolución de llamada mediante el parámetro opcional asyncContext .

La siguiente función de JavaScript, removeAttachment, continúa ampliando los ejemplos anteriores y quita los datos adjuntos especificados del correo electrónico o la cita que se va a componer. La función usa como argumento el id. de los datos adjuntos que se van a quitar. Puede obtener el identificador de los datos adjuntos después de una addFileAttachmentAsyncllamada correcta al método , addFileAttachmentFromBase64Asynco addItemAttachmentAsync y usarlo en una llamada de método posterior removeAttachmentAsync . También puede llamar a getAttachmentsAsync (incluido en el conjunto de requisitos 1.8) para obtener los datos adjuntos y sus identificadores para esa sesión de complemento.

// Removes the specified attachment from the composed item.
function removeAttachment(attachmentId) {
    // When the attachment is removed, the callback function is invoked.
    // Here, the callback function uses an asyncResult parameter and
    // gets the ID of the removed attachment if the removal succeeds.
    // You can optionally pass any object you wish to access in the
    // callback function as an argument to the asyncContext parameter.
    Office.context.mailbox.item.removeAttachmentAsync(
        attachmentId,
        { asyncContext: null },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            console.log(`Removed attachment with the ID: ${asyncResult.value}`);
        }
    );
}

Sugerencia

El removeAttachmentAsync método no quita los datos adjuntos insertados de un elemento de correo. Para quitar los datos adjuntos insertados, primero obtenga el cuerpo del elemento y, a continuación, quite las referencias de los datos adjuntos de su contenido. Use las API de Office.Body para obtener y establecer el cuerpo de un elemento.

Recursos adicionales