Compartilhar via

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

  • Artigo

A API javaScript do Office fornece várias APIs para gerir os anexos de um item quando o utilizador está a compor uma mensagem ou compromisso.

Anexar um ficheiro ou item do Outlook

Anexe um ficheiro ou item do Outlook a um formulário de composição com o 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 status, 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. Para obter mais exemplos sobre a transmissão de parâmetros opcionais para métodos assíncronos na plataforma suplementos do Office, consulte Programação assíncrona em 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);

Para marcar o resultado de uma chamada de método assíncrono na função de chamada de retorno, utilize as status propriedades e error do AsyncResult objeto. Se a anexação for concluída com êxito, utilize 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.

Observação

O URI do ficheiro a anexar tem de suportar a colocação em cache na produção. O servidor que aloja a imagem não deve devolver um Cache-Control cabeçalho que especifique no-cache, no-storeou opções semelhantes na resposta HTTP. No entanto, quando estiver a desenvolver o suplemento e a fazer alterações aos ficheiros, a colocação em cache pode impedi-lo de ver as suas alterações. Recomendamos a utilização de Cache-Control cabeçalhos durante o desenvolvimento.

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

// 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 adicionar uma imagem codificada em Base64 inline 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.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.");
        });
    });
});

Anexar um item do Outlook

Para 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, especifique o ID dos Serviços Web exchange (EWS) do item e utilize o addItemAttachmentAsync método . Para obter o ID do EWS do item, utilize a propriedade item.itemId .

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

// 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}`);
        }
    );
}

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. 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 seguintes APIs para obter anexos no modo de composição estão disponíveis no conjunto de requisitos 1.8.

Utilize 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, utilize o método getAttachmentContentAsync . Os formatos suportados estão listados na enumeração AttachmentContentFormat .

Deve fornecer uma função de chamada de retorno para marcar para o status e qualquer erro ao utilizar 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.
  }
}

Dica

Se o cliente do Outlook no qual o seu suplemento está em execução não suportar o requisito da Caixa de Correio definido como 1.8, ainda pode obter um anexo e os respetivos conteúdos de um item que está a ser composto através do Microsoft Graph ou do EWS. Para saber mais, consulte Obter anexos de um item do Outlook a partir do Exchange.

Remover um anexo

Para remover um ficheiro ou anexo de item de uma mensagem ou item de compromisso num formulário de composição, especifique o ID de anexo correspondente no 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 marcar para o status e qualquer erro ao utilizar 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 },
        (asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.error(asyncResult.error.message);
                return;
            }

            console.log(`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