Marcar automaticamente para um anexo antes que uma mensagem seja enviada

  • Artigo

Nunca mais perca a anexação de um documento ou foto importante à sua mensagem. Com um suplemento baseado em evento, suas mensagens são verificadas automaticamente para anexos antes de serem enviadas, para que você possa ter certeza de que está sempre enviando uma versão completa.

As seções a seguir orientam como desenvolver um suplemento baseado em evento que implementa alertas inteligentes para lidar com o OnMessageSend evento. Ao final deste passo a passo, seu suplemento marcar automaticamente para um documento ou imagem anexado mencionado na mensagem e alertará você se ele estiver ausente antes que a mensagem seja enviada.

Observação

Os OnMessageSend eventos e OnAppointmentSend foram introduzidos no conjunto de requisitos 1.12. Para verificar se o cliente do Outlook dá suporte a esses eventos, consulte Clientes e plataformas com suporte.

Configurar seu ambiente

Antes de iniciar o passo a passo, verifique se o cliente do Outlook dá suporte ao recurso Alertas Inteligentes. Para obter diretrizes, consulte Clientes e plataformas com suporte.

Em seguida, conclua o início rápido do Outlook, que cria um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

Para configurar o manifesto, selecione a guia para o tipo de manifesto que você está usando.

  1. Abra o arquivo manifest.json .

  2. Adicione o objeto a seguir à matriz "extensions.runtimes". Observe o seguinte sobre esta marcação:

    • A "minVersion" do conjunto de requisitos da caixa de correio é definida como "1.12" porque a tabela de eventos com suporte especifica que esta é a versão mais baixa do conjunto de requisitos que dá suporte ao OnMessageSend evento.
    • A "id" do runtime é definida como o nome descritivo "autorun_runtime".
    • A propriedade "code" tem uma propriedade filho "page" definida como um arquivo HTML e uma propriedade filho "script" definida como um arquivo JavaScript. Você criará ou editará esses arquivos em etapas posteriores. O Office usa um desses valores ou outro, dependendo da plataforma.
      • O Outlook clássico no Windows executa o manipulador de eventos em um runtime somente JavaScript, que carrega um arquivo JavaScript diretamente.
      • Outlook na Web, no Mac, e no novo Outlook no Windows (versão prévia) execute o manipulador em um runtime do navegador, que carrega um arquivo HTML. Esse arquivo, por sua vez, contém uma <script> marca que carrega o arquivo JavaScript. Para obter mais informações, consulte Runtimes em Suplementos do Office.
    • A propriedade "lifetime" é definida como "curta", o que significa que o runtime é iniciado quando o evento é disparado e desligado quando o manipulador é concluído. (Em certos casos raros, o runtime é desligado antes da conclusão do manipulador. Consulte Runtimes em Suplementos do Office.)
    • Há uma ação para executar um manipulador para o OnMessageSend evento. Você criará a função de manipulador em uma etapa posterior.
     {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.12"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onMessageSendHandler",
            "type": "executeFunction",
            "displayName": "onMessageSendHandler"
        }
    ]
}

  3. Adicione a seguinte matriz "autoRunEvents" como uma propriedade do objeto na matriz "extensões".

    "autoRunEvents": [

]

  4. Adicione o objeto a seguir à matriz "autoRunEvents". Observe o seguinte sobre este código:

    • O objeto de evento atribui uma função manipulador ao OnMessageSend evento (usando o nome do manifesto unificado do evento, "messageSending", conforme descrito na tabela de eventos com suporte). O nome da função fornecido em "actionId" deve corresponder ao nome usado na propriedade "id" do objeto na matriz "actions" em uma etapa anterior.
    • A opção "sendMode" está definida como "softBlock". Isso significa que, se a mensagem não atender às condições que o suplemento define para envio, o usuário deverá agir antes de poder enviar a mensagem. No entanto, se o suplemento não estiver disponível no momento do envio, o item será enviado.
      {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.12"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
        {
            "type": "messageSending",
            "actionId": "onMessageSendHandler",
            "options": {
                "sendMode": "softBlock"
            }
        }
      ]
  }

Dica

Implementar o tratamento de eventos

Você precisa implementar o tratamento para o evento selecionado.

Nesse cenário, você adicionará tratamento para enviar uma mensagem. Seu suplemento marcar para determinadas palavras-chave na mensagem. Se alguma dessas palavras-chave for encontrada, ela marcar se houver anexos. Se não houver anexos, seu suplemento recomendará ao usuário adicionar o anexo possivelmente ausente.

  1. No mesmo projeto de início rápido, crie uma nova pasta chamada launchevent no diretório ./src .

  2. Na pasta ./src/launchevent , crie um novo arquivo chamado launchevent.js.

  3. Abra o arquivo ./src/launchevent/launchevent.js no editor de código e adicione o código JavaScript a seguir.

    /*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/

function onMessageSendHandler(event) {
  Office.context.mailbox.item.body.getAsync(
    "text",
    { asyncContext: event },
    getBodyCallback
  );
}

function getBodyCallback(asyncResult){
  const event = asyncResult.asyncContext;
  let body = "";
  if (asyncResult.status !== Office.AsyncResultStatus.Failed && asyncResult.value !== undefined) {
    body = asyncResult.value;
  } else {
    const message = "Failed to get body text";
    console.error(message);
    event.completed({ allowEvent: false, errorMessage: message });
    return;
  }

  const matches = hasMatches(body);
  if (matches) {
    Office.context.mailbox.item.getAttachmentsAsync(
      { asyncContext: event },
      getAttachmentsCallback);
  } else {
    event.completed({ allowEvent: true });
  }
}

function hasMatches(body) {
  if (body == null || body == "") {
    return false;
  }

  const arrayOfTerms = ["send", "picture", "document", "attachment"];
  for (let index = 0; index < arrayOfTerms.length; index++) {
    const term = arrayOfTerms[index].trim();
    const regex = RegExp(term, 'i');
    if (regex.test(body)) {
      return true;
    }
  }

  return false;
}

function getAttachmentsCallback(asyncResult) {
  const event = asyncResult.asyncContext;
  if (asyncResult.value.length > 0) {
    for (let i = 0; i < asyncResult.value.length; i++) {
      if (asyncResult.value[i].isInline == false) {
        event.completed({ allowEvent: true });
        return;
      }
    }

    event.completed({
      allowEvent: false,
      errorMessage: "Looks like the body of your message includes an image or an inline file. Attach a copy to the message before sending."
    });
  } else {
    event.completed({
      allowEvent: false,
      errorMessage: "Looks like you're forgetting to include an attachment."
    });
  }
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onMessageSendHandler", onMessageSendHandler);
}

Importante

Ao desenvolver o suplemento Alertas Inteligentes para ser executado no Outlook no Windows, tenha o seguinte em mente.

  • No momento, não há suporte para importações no arquivo JavaScript em que você implementa o tratamento para ativação baseada em eventos.
  • Para garantir que o suplemento seja executado conforme o esperado quando um OnMessageSend evento ou OnAppointmentSend ocorrer no Outlook no Windows, chame Office.actions.associate o arquivo JavaScript em que seus manipuladores são implementados. Isso mapeia o nome do manipulador de eventos especificado no manifesto para seu equivalente JavaScript. Se essa chamada não estiver incluída em seu arquivo JavaScript e a propriedade de modo de envio do manifesto estiver definida como soft block ou não for especificada, seus usuários serão impedidos de enviar mensagens ou reuniões.

Personalizar o botão Não Enviar (opcional) (versão prévia)

Observação

O recurso de personalização do botão Não Enviar está atualmente em versão prévia no Outlook no Windows. Os recursos na versão prévia não devem ser usados em suplementos de produção. Convidamos você a experimentar esse recurso em ambientes de teste ou desenvolvimento e receber comentários sobre sua experiência por meio do GitHub (confira a seção Comentários no final desta página).

Para visualizar esse recurso no Outlook no Windows, você deve instalar a versão 2308 (Build 16731.20000) ou posterior. Em seguida, insira o programa Microsoft 365 Insider e selecione a opção Canal Beta para acessar builds beta do Office.

Se um item de email não atender às condições de um suplemento de Alertas Inteligentes, uma caixa de diálogo será mostrada ao usuário para alertá-los de que ações adicionais podem ser necessárias antes que um item possa ser enviado. A opção de modo de envio especificada no manifesto determina as opções que aparecem para o usuário na caixa de diálogo. A opção Não Enviar aparece na caixa de diálogo, não importa qual opção de modo de envio você selecione. Por padrão, selecionar Não Enviar cancela a operação de envio e fecha a caixa de diálogo. Para fornecer ao usuário mais diretrizes sobre como atender às condições do suplemento, personalize o texto deste botão e programe-o para abrir um painel de tarefas em que você pode fornecer informações e funcionalidades adicionais.

Modificar o texto e a funcionalidade do botão Não Enviar

Para modificar o texto do botão Não Enviar ou atribuí-lo a um comando de painel de tarefas, você deve definir opções adicionais no método event.completed do manipulador de eventos.

  • A opção cancelLabel personaliza o texto do botão Não Enviar . O texto personalizado deve ter no máximo 20 caracteres.

  • A opção commandId especifica a ID do painel de tarefas que é aberto quando o botão Não Enviar é selecionado. O valor deve corresponder à ID do painel de tarefas no manifesto do suplemento. A marcação depende do tipo de manifesto que seu suplemento usa.

    • Manifesto XML: o id atributo do <elemento Control> que representa o painel de tarefas.
    • Manifesto unificado para o Microsoft 365 (versão prévia): a propriedade "id" do comando do painel de tarefas na matriz "controles".

  • A opção contextData especifica todos os dados JSON que você deseja passar para o suplemento quando o botão Não Enviar estiver selecionado. Se você incluir essa opção, também deverá definir a opção commandId . Caso contrário, os dados JSON serão ignorados.

    Dica

    Para recuperar o valor da opção contextData , você deve chamar Office.context.mailbox.item.getInitializationContextAsync na implementação javaScript do painel de tarefas.

  1. Navegue até a pasta ./src/launchevent e abra launchevent.js.

  2. Substitua a função getAttachmentsCallback pelo código a seguir.

    function getAttachmentsCallback(asyncResult) {
  const event = asyncResult.asyncContext;
  if (asyncResult.value.length > 0) {
    for (let i = 0; i < asyncResult.value.length; i++) {
      if (asyncResult.value[i].isInline == false) {
        event.completed({ allowEvent: true });
        return;
      }
    }

    event.completed({
      allowEvent: false,
      errorMessage: "Looks like the body of your message includes an image or an inline file. Attach a copy to the message before sending.",
      cancelLabel: "Add an attachment",
      commandId: "msgComposeOpenPaneButton"
    });
  } else {
    event.completed({
      allowEvent: false,
      errorMessage: "Looks like you're forgetting to include an attachment.",
      cancelLabel: "Add an attachment",
      commandId: "msgComposeOpenPaneButton"
    });
  }
}

  3. Salve suas alterações.

Substituir a opção de modo de envio no runtime (opcional) (versão prévia)

Observação

O recurso de substituição de opção de modo de envio está atualmente em versão prévia no Outlook no Windows. Os recursos na versão prévia não devem ser usados em suplementos de produção. Convidamos você a experimentar esse recurso em ambientes de teste ou desenvolvimento e receber comentários sobre sua experiência por meio do GitHub (confira a seção Comentários no final desta página).

Para visualizar esse recurso no Outlook no Windows, você deve instalar a versão 2308 (Build 16731.20000) ou posterior. Em seguida, insira o programa Microsoft 365 Insider e selecione a opção Canal Beta para acessar builds beta do Office.

Pode haver instâncias quando você deseja que seu suplemento implemente diferentes opções de modo de envio. Por exemplo, você pode querer que seu suplemento imponha a opção de bloco em itens de email que não atendem às políticas de proteção de informações da sua organização, mas só faça com que ele aplique a opção de usuário prompt para fornecer uma recomendação se um usuário adicionar o destinatário incorreto.

Para substituir a opção de modo de envio no runtime, você deve definir a opção sendModeOverride no event.completed método do manipulador de eventos.

  1. Navegue até a pasta ./src/launchevent e abra launchevent.js.

  2. Substitua a função getAttachmentsCallback pelo código a seguir.

    function getAttachmentsCallback(asyncResult) {
  const event = asyncResult.asyncContext;
  if (asyncResult.value.length > 0) {
    for (let i = 0; i < asyncResult.value.length; i++) {
      if (asyncResult.value[i].isInline == false) {
        event.completed({ allowEvent: true });
        return;
      }
    }

    event.completed({
      allowEvent: false,
      errorMessage: "Looks like the body of your message includes an image or an inline file. Would you like to attach a copy of it to the message?",
      cancelLabel: "Attach a copy",
      commandId: "msgComposeOpenPaneButton",
      sendModeOverride: Office.MailboxEnums.SendModeOverride.PromptUser
    });
  } else {
    event.completed({
      allowEvent: false,
      errorMessage: "Looks like you're forgetting to include an attachment.",
      cancelLabel: "Add an attachment",
      commandId: "msgComposeOpenPaneButton"
    });
  }
}

  3. Salve suas alterações.

Configurar o painel de tarefas (opcional)

Se você implementou as etapas opcionais para personalizar o botão Não Enviar ou substituir a opção de modo de envio neste passo a passo, você também precisará configurar o painel de tarefas. Embora o painel de tarefas seja necessário nesta implementação, não é um requisito personalizar o texto do botão Não Enviar ou substituir a opção de modo de envio.

  1. Navegue até a pasta ./src/taskpane e abra taskpane.html.

  2. Selecione todo <o nó do corpo> (incluindo suas marcas abertas e fechadas) e substitua-o pelo código a seguir.

    <body class="ms-welcome ms-Fabric">
    <header class="ms-welcome__header ms-bgColor-neutralLighter">
        <img width="90" height="90" src="../../assets/logo-filled.png" alt="Contoso" title="Contoso" />
        <h1 class="ms-font-su">Try out the Smart Alerts sample</h1>
    </header>
    <section id="sideload-msg" class="ms-welcome__main">
        <h2 class="ms-font-xl">Please <a href="https://learn.microsoft.com/office/dev/add-ins/testing/test-debug-office-add-ins#sideload-an-office-add-in-for-testing">sideload</a> your add-in to see app body.</h2>
    </section>
    <main id="app-body" class="ms-welcome__main" style="display: none;">
        <p>
            This sample implements a Smart Alerts add-in that activates when you forget to attach a document or picture that you mention in your message.
            To learn more, see the <a href="https://learn.microsoft.com/office/dev/add-ins/outlook/smart-alerts-onmessagesend-walkthrough">Smart Alerts walkthrough</a>.
        </p>
        <h3 class="ms-font-l">Add an attachment</h3>
        <p>Add the URL of a file to add it as an attachment.</p>
        <div class="ms-TextField">
            <label class="ms-Label ms-font-l">URL of file:</label>
            <input id="attachment-url" class="ms-TextField-field" type="text" value="https://localhost:3000/assets/icon-128.png" placeholder="">
        </div>
        <br/>
        <button class="ms-Button ms-Button--primary">
            <span id="add-attachment" class="ms-Button-label">Add as attachment</span>
        </button>
        <br/>
        <h3 class="ms-font-l">Override the send mode option at runtime</h3>
        <p>Add an inline image to test overriding the send mode option at runtime.</p>
        <button class="ms-Button ms-Button--primary">
            <span id="add-inline-image" class="ms-Button-label">Add an inline image</span>
        </button>
    </main>
</body>

  3. Salve suas alterações.

  4. Na mesma pasta ./src/taskpane , abra taskpane.js.

  5. Substitua seu conteúdo pelo código a seguir.

    /*
 * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 * See LICENSE in the project root for license information.
 */

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("add-attachment").onclick = addAttachment;
    document.getElementById("add-inline-image").onclick = addInlineImage;
  }
});

// Adds the specified URL as an attachment to the message.
export async function addAttachment() {
  const attachmentUrl = document.querySelector("#attachment-url").value;
  Office.context.mailbox.item.addFileAttachmentAsync(attachmentUrl, getFileName(attachmentUrl), (asyncResult) => {
    console.log(asyncResult);
  });
}

// Gets the file name from a URL.
function getFileName(url) {
  const lastIndex = url.lastIndexOf("/");
  if (lastIndex >= 0) {
    return url.substring(lastIndex + 1);
  }

  return url;
}

// Adds an inline image to the body of the message.
export async function addInlineImage() {
  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==";

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

    // Inserts the Base64-encoded 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.Failed) {
        console.log(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.log(setResult.error.message);
          return;
        }

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

  6. Salve suas alterações.

Atualizar o arquivo HTML de comandos

  1. Na pasta ./src/commands , abra commands.html.

  2. Imediatamente antes da marca de cabeça de fechamento (</head>), adicione uma entrada de script para o código JavaScript que manipula eventos.

    <script type="text/javascript" src="../launchevent/launchevent.js"></script>

Importante

Os recursos de substituição de opções de modo de envio e personalização do botão Não Enviar estão atualmente em versão prévia no Outlook no Windows. Se você estiver testando esses recursos em seu projeto de suplemento, deverá incluir uma referência à versão prévia da API JavaScript do Office no arquivo commands.html .

<script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
  1. Salve suas alterações.

Atualizar as configurações webpack config

  1. Abra o arquivo webpack.config.js encontrado no diretório raiz do projeto e conclua as etapas a seguir.

  2. Localize a plugins matriz dentro do config objeto e adicione este novo objeto ao início da matriz.

    new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/launchevent/launchevent.js",
      to: "launchevent.js",
    },
  ],
}),

  3. Salve suas alterações.

Experimente

  1. Execute os comandos a seguir no diretório raiz do seu projeto. Quando você executar npm start, o servidor Web local será iniciado (se ainda não estiver em execução) e o suplemento será sideload.

    npm run build

    npm start

    Observação

    Se o suplemento não tiver sido carregado automaticamente, siga as instruções nos suplementos do Sideload Outlook para testar para carregar manualmente o suplemento no Outlook.

  2. No cliente preferido do Outlook, crie uma nova mensagem e defina o assunto. No corpo, adicione algum texto. Por exemplo, "Aqui está uma imagem do logotipo proposto".

  3. Envie a mensagem. Uma caixa de diálogo aparece solicitando que você adicione um anexo. Selecione Não Enviar ou Adicionar um anexo. A opção disponível para você depende se você implementou a etapa opcional para personalizar o botão Não Enviar .

    • Botão Padrão Não Enviar .

      Caixa de diálogo solicitando que o usuário adicione um anexo à mensagem.

    • Botão Adicionar um anexo personalizado.

      Caixa de diálogo com um botão Personalizado Não Enviar solicitando que o usuário adicione um anexo à mensagem.

    Dica

    Se você atribuir um painel de tarefas ao botão Não Enviar , fechar a caixa de diálogo também abrirá o painel de tarefas especificado.

  4. Adicione um anexo à sua mensagem. Se você implementou a etapa opcional para personalizar o botão Não Enviar , use o painel de tarefas para adicionar um anexo.

    Painel de tarefas com uma opção para adicionar um anexo.

  5. Envie a mensagem. Não deve haver alerta desta vez.

Experimente substituir a opção de modo de envio no runtime (opcional)

Se você implementou a etapa opcional para substituir a opção de modo de envio no runtime, execute o seguinte para experimentá-lo.

  1. Execute npm start no diretório raiz do seu projeto. Isso inicia o servidor Web local (se ele ainda não estiver em execução) e sideload seu suplemento.

    Observação

    Se o suplemento não tiver sido carregado automaticamente, siga as instruções nos suplementos do Sideload Outlook para testar para carregar manualmente o suplemento no Outlook.

  2. No Outlook no Windows, crie uma nova mensagem e defina o assunto. No corpo, adicione algum texto. Por exemplo, "Aqui está uma imagem do logotipo proposto".

  3. Na faixa de opções, selecione Contoso Add-in>Show Taskpane.

  4. No painel de tarefas, selecione Adicionar uma imagem embutida. Uma imagem é adicionada ao corpo da mensagem.

  5. Envie a mensagem. Uma caixa de diálogo aparece recomendando anexar uma cópia da imagem à mensagem.

  6. Selecione Enviar De qualquer maneira para enviar a mensagem como está ou selecione Anexar uma cópia para incluir uma cópia antes de enviar a mensagem.

    Caixa de diálogo Alertas Inteligentes com a opção Enviar De qualquer maneira disponível no runtime.

Importante

Se um suplemento alertas inteligentes que implementa o recurso de substituição não puder concluir o processamento de um evento devido a um erro ou não estiver disponível quando o evento ocorrer, ele usará a opção de modo de envio especificada no manifesto.

Confira também