Partilhar via

Gerir anexos de um item num formulário de composição no Outlook

  • Artigo

A API JavaScript do Office fornece várias APIs que pode utilizar para gerir os anexos de um item quando o utilizador estiver a compor.

Anexar um ficheiro ou item do Outlook

Pode anexar um ficheiro ou item do Outlook a um formulário de composição através do método adequado para o tipo de anexo.

Estes são métodos assíncronos, o que significa que a execução pode continuar sem esperar que a ação seja concluída. Dependendo da localização original e do tamanho do anexo que está a ser adicionado, a chamada assíncrona pode demorar algum tempo a concluir.

Se existirem tarefas que dependam da ação a concluir, deve realizar essas tarefas numa função de chamada de retorno. Esta função de chamada de retorno é opcional e é invocada quando o carregamento do anexo é concluído. A função de chamada de retorno utiliza um objeto AsyncResult como um parâmetro de saída que fornece qualquer estado, erro e valor devolvido da adição do anexo. Se o retorno de chamada requer parâmetros adicionais, você pode especificá-los no parâmetro opcional options.asyncContext. options.asyncContext pode ser de qualquer tipo que a sua função de chamada de retorno espera.

Por exemplo, pode definir options.asyncContext como um objeto JSON que contém um ou mais pares chave-valor. Pode encontrar mais exemplos sobre a transmissão de parâmetros opcionais para métodos assíncronos na plataforma Suplementos do Office na programação assíncrona nos Suplementos do Office. O exemplo seguinte mostra como utilizar o asyncContext parâmetro para transmitir dois argumentos para uma função de chamada de retorno.

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

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

Pode verificar o êxito ou o erro de uma chamada de método assíncrona na função de chamada de retorno com as status propriedades e error do AsyncResult objeto. Se a anexação for concluída com êxito, pode utilizar a AsyncResult.value propriedade para obter o ID do anexo. A ID do anexo é um número inteiro que você pode usar posteriormente para remover o anexo.

Observação

O ID do anexo é válido apenas na mesma sessão e não é garantido que mapeie para o mesmo anexo em todas as sessões. Os exemplos de quando uma sessão termina incluem quando o utilizador fecha o suplemento ou se o utilizador começa a compor num formulário inline e, posteriormente, apresenta o formulário inline para continuar numa janela separada.

Dica

Existem limites para os ficheiros ou itens do Outlook que pode anexar a um item de correio, como o número de anexos e o respetivo tamanho. Para obter mais orientações, veja Limites da API javaScript.

Anexar um ficheiro

Pode anexar um ficheiro a uma mensagem ou compromisso num formulário de composição utilizando o addFileAttachmentAsync método e especificando o URI do ficheiro. Também pode utilizar o addFileAttachmentFromBase64Async método , especificando a cadeia codificada em Base64 como entrada. Se o arquivo estiver protegido, você poderá incluir uma identidade ou um token de autenticação apropriado como um parâmetro de cadeia de caracteres de consulta de URI. O Exchange fará uma chamada à URI para obter o anexo, e o serviço Web que protege o arquivo precisará usar o token como um meio de autenticação.

O exemplo de JavaScript a seguir é um suplemento de composição que anexa um arquivo, picture.png, de um servidor Web à mensagem ou ao compromisso que está sendo redigido. A função de chamada de retorno utiliza asyncResult como parâmetro, verifica o estado do resultado e obtém o ID do anexo se o método for bem-sucedido.

Office.initialize = function () {
    // Checks for the DOM to load using the jQuery ready method.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // 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: null },
            function (asyncResult) {
                if (asyncResult.status === Office.AsyncResultStatus.Failed){
                    write(asyncResult.error.message);
                } else {
                    // Get the ID of the attached file.
                    const attachmentID = asyncResult.value;
                    write('ID of added attachment: ' + attachmentID);
                }
            });
    });
}

// Writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Para adicionar uma imagem inline base64 ao corpo de uma mensagem ou compromisso que está a ser composto, primeiro tem de obter o corpo do item atual com o Office.context.mailbox.item.body.getAsync método antes de inserir a imagem com o addFileAttachmentFromBase64Async método . Caso contrário, a imagem não será composta no corpo depois de ser inserida. Para obter orientações, veja o seguinte exemplo de JavaScript, que adiciona uma imagem Base64 inline ao início de um corpo de item.

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.Succeeded) {
    // Insert the Base64 image to the beginning of the body.
    const options = { isInline: true, asyncContext: bodyResult.value };
    mailItem.addFileAttachmentFromBase64Async(base64String, "sample.png", options, (attachResult) => {
      if (attachResult.status === Office.AsyncResultStatus.Succeeded) {
        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.Succeeded) {
            console.log("Inline Base64 image added to the body.");
          } else {
            console.log(setResult.error.message);
          }
        });
      } else {
        console.log(attachResult.error.message);
      }
    });
  } else {
    console.log(bodyResult.error.message);
  }
});

Anexar um item do Outlook

Pode anexar um item do Outlook (por exemplo, e-mail, calendário ou item de contacto) a uma mensagem ou compromisso num formulário de composição ao especificar o ID dos Serviços Web exchange (EWS) do item e ao utilizar o addItemAttachmentAsync método . Pode obter o ID do EWS de um e-mail, calendário, contacto ou item de tarefa na caixa de correio do utilizador utilizando o método mailbox.makeEwsRequestAsync e acedendo à operação EWS FindItem. A propriedade item.itemId também fornece a ID dos EWS de um item existente em um formulário de leitura.

A seguinte função JavaScript, addItemAttachment, expande o primeiro exemplo acima e adiciona um item como anexo ao e-mail ou compromisso que está a ser composto. A função utiliza como argumento a ID dos EWS do item que será anexado. Se a anexação for bem-sucedida, obtém o ID do anexo para processamento adicional, incluindo remover esse anexo na mesma sessão.

// 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: null },
        function (asyncResult) {
            if (asyncResult.status === Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            } else {
                const attachmentID = asyncResult.value;
                write('ID of added attachment: ' + attachmentID);
            }
        });
}

Observação

Pode utilizar um suplemento de composição para anexar uma instância de um compromisso periódico no Outlook na Web, em dispositivos móveis ou no novo Outlook no Windows (pré-visualização). No entanto, num cliente do Outlook de suporte no Windows ou no Mac, tentar anexar uma instância resultaria na anexação da série periódica (o compromisso principal).

Obter anexos

As APIs para obter anexos no modo de composição estão disponíveis no conjunto de requisitos 1.8.

Pode utilizar o método getAttachmentsAsync para obter os anexos da mensagem ou compromisso que está a ser composto.

Para obter o conteúdo de um anexo, pode utilizar o método getAttachmentContentAsync . Os formatos suportados estão listados na enumeração AttachmentContentFormat .

Deve fornecer uma função de chamada de retorno para verificar o estado e qualquer erro com o objeto do AsyncResult parâmetro de saída. Também pode transmitir quaisquer parâmetros adicionais para a função de chamada de retorno com o parâmetro opcional asyncContext .

O exemplo de JavaScript seguinte obtém os anexos e permite-lhe configurar um processamento distinto para cada formato de anexo suportado.

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.
  }
}

Remover um anexo

Pode remover um ficheiro ou anexo de item de uma mensagem ou item de compromisso num formulário de composição ao especificar o ID de anexo correspondente ao utilizar o método removeAttachmentAsync .

Importante

Se estiver a utilizar o conjunto de requisitos 1.7 ou anterior, só deve remover anexos que o mesmo suplemento tenha adicionado na mesma sessão.

Semelhante aos addFileAttachmentAsyncmétodos , addItemAttachmentAsynce getAttachmentsAsync é removeAttachmentAsync um método assíncrono. Deve fornecer uma função de chamada de retorno para verificar o estado e qualquer erro com o objeto do AsyncResult parâmetro de saída. Também pode transmitir quaisquer parâmetros adicionais para a função de chamada de retorno com o parâmetro opcional asyncContext .

A seguinte função JavaScript, removeAttachment, continua a expandir os exemplos acima e remove o anexo especificado do e-mail ou compromisso que está a ser composto. A função utiliza como argumento a ID do anexo a ser removido. Pode obter o ID de um anexo após uma chamada com êxito addFileAttachmentAsync, addFileAttachmentFromBase64Asyncou addItemAttachmentAsync método e utilizá-lo numa chamada de método subsequente removeAttachmentAsync . Também pode chamar getAttachmentsAsync (introduzido no requisito definido como 1.8) para obter os anexos e os respetivos IDs para essa sessão de suplemento.

// 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 },
        function (asyncResult) {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                write(asyncResult.error.message);
            } else {
                write('Removed attachment with the ID: ' + asyncResult.value);
            }
        });
}

Dica

O removeAttachmentAsync método não remove anexos inline de um item de correio. Para remover um anexo inline, primeiro obtenha o corpo do item e, em seguida, remova quaisquer referências do anexo do respetivo conteúdo. Utilize as APIs Office.Body para obter e definir o corpo de um item.

Confira também