Anteponer o anexar contenido a un cuerpo de mensaje o cita al enviar

  • Artículo

Las características prepend-on-send y append-on-send permiten al complemento de Outlook insertar contenido en el cuerpo de un mensaje o cita cuando se envía el elemento de correo. Estas características aumentan aún más la productividad y la seguridad de los usuarios al permitirles:

  • Agregue etiquetas de confidencialidad y clasificación a sus mensajes y citas para facilitar la identificación y la organización de elementos.
  • Insertar declinaciones de responsabilidades con fines legales.
  • Agregue encabezados estandarizados con fines de marketing y comunicación.

En este tutorial, desarrollará un complemento que anteponga un encabezado y anexa una declinación de responsabilidades cuando se envía un mensaje.

Nota:

La compatibilidad con la característica append-on-send se introdujo en el conjunto de requisitos 1.9, mientras que la compatibilidad con la característica prepend-on-send se introdujo en el conjunto de requisitos 1.13. Consulte clientes y plataformas que admiten estos conjuntos de requisitos.

Configurar el entorno

Complete el inicio rápido de Outlook que crea un proyecto de complemento con el generador de Yeoman para complementos de Office.

Configuración del manifiesto

Para configurar el manifiesto, seleccione la pestaña del tipo de manifiesto que usará.

A continuación se muestra cómo configurar el manifiesto unificado para habilitar las características prepend-on-send y append-on-send.

  1. Abra el archivo manifest.json .

  2. Agregue el siguiente objeto a la matriz "extensions.runtimes". Tenga en cuenta lo siguiente sobre este código.

    • La "minVersion" del conjunto de requisitos de Buzón se establece en "1.13", por lo que el complemento no se puede instalar en plataformas y versiones de Office en las que no se admite esta característica.
    • El "id" del tiempo de ejecución se establece en el nombre descriptivo, "function_command_runtime".
    • La propiedad "code.page" se establece en la dirección URL del archivo HTML sin interfaz de usuario que cargará el comando de función.
    • La propiedad "lifetime" se establece en "short", lo que significa que el tiempo de ejecución se inicia cuando se selecciona el botón de comando de función y se cierra cuando se completa la función. (En algunos casos poco frecuentes, el tiempo de ejecución se cierra antes de que se complete el controlador. Consulte Tiempos de ejecución en complementos de Office).
    • Hay acciones especificadas para ejecutar las funciones "prependHeaderOnSend" y "appendDisclaimerOnSend". Estas funciones se crearán en un paso posterior.
    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    },
    "id": "function_command_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "prependHeaderOnSend",
            "type": "executeFunction",
            "displayName": "prependHeaderOnSend"
        },
        {
            "id": "appendDisclaimerOnSend",
            "type": "executeFunction",
            "displayName": "appendDisclaimerOnSend"
        }
    ]
}

  3. Agregue el siguiente objeto a la matriz "extensions.ribbons". Tenga en cuenta lo siguiente sobre este código.

    • El valor "mailCompose" se agrega a la matriz "contexts" para exponer los botones prepend-on-send y append-on-send en una ventana de redacción.
    • Los objetos "controls" crean y configuran los botones para las funciones prepend-on-send y append-on-send. La propiedad "actionId" de cada objeto debe reflejar el mismo valor especificado en la propiedad "actions.id" aplicable del objeto "extensions.runtimes".
    {
    "contexts": [
        "mailCompose"
    ],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "msgComposeGroup",
                    "label": "Contoso Add-in",
                    "icons": [
                        {
                            "size": 16,
                            "url" "https://localhost:3000/assets/icon-16.png"
                        },
                        {
                            "size": 32,
                            "url" "https://localhost:3000/assets/icon-32.png"
                        },
                        {
                            "size": 80,
                            "url" "https://localhost:3000/assets/icon-80.png"
                        }
                    ],
                    "controls": [
                        {
                            "id": "PrependButton",
                            "type": "button",
                            "label": "Prepend header",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Prepend header on send",
                                "description": "Prepend the Contoso header on send."
                            },
                            "actionId": "prependHeaderOnSend"
                        },
                        {
                            "id": "AppendButton",
                            "type": "button",
                            "label": "Add disclaimer",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Append disclaimer on send",
                                "description": "Append the Contoso disclaimer on send."
                            },
                            "actionId": "appendDisclaimerOnSend"
                        }
                    ]
                }
            ]
        }
    ]
}

  4. En la matriz "authorization.permissions.resourceSpecific", agregue el siguiente objeto. Asegúrese de que está separado de otros objetos de la matriz con una coma.

    {
  "name": "Mailbox.AppendOnSend.User",
  "type": "Delegated"
}

  5. Guarde los cambios.

Sugerencia

  • El usuario debe activar las características prepend-on-send y append-on-send a través de un panel de tareas o un botón de comando de función. Si desea que el contenido se anteponga o anexe al envío sin que el usuario realice ninguna acción adicional, puede implementar estas características en un complemento de activación basado en eventos.
  • Para obtener más información sobre los manifiestos de los complementos de Outlook, consulte Manifiestos de complementos de Office.

Implementación del controlador prepend-on-send

En esta sección, implementará el código JavaScript para anteponer un encabezado de empresa de ejemplo a un elemento de correo cuando se envíe.

  1. Vaya a la carpeta ./src/commands del proyecto y abra el archivo commands.js .

  2. Inserte la siguiente función al final del archivo.

    function prependHeaderOnSend(event) {
  // It's recommended to call the getTypeAsync method and pass its returned value to the options.coercionType parameter of the prependOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      // Sets the header to be prepended to the body of the message on send.
      const bodyFormat = asyncResult.value;
      // Because of the various ways in which HTML text can be formatted, the content may render differently when it's prepended to the mail item body.
      // In this scenario, a <br> tag is added to the end of the HTML string to preserve its format.
      const header = '<div style="border:3px solid #000;padding:15px;"><h1 style="text-align:center;">Contoso Limited</h1></div><br>';

      Office.context.mailbox.item.body.prependOnSendAsync(
        header,
        {
          asyncContext: asyncResult.asyncContext,
          coercionType: bodyFormat
        },
        (asyncResult) => {
          if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
          }

          console.log("The header will be prepended when the mail item is sent.");
          asyncResult.asyncContext.completed();
        }
      );
  });
}

  3. Guarde los cambios.

Implementación del controlador append-on-send

En esta sección, implementará el código JavaScript para anexar una declinación de responsabilidades de empresa de ejemplo a un elemento de correo cuando se envíe.

  1. En el mismo archivo commands.js , inserte la siguiente función después de la prependHeaderOnSend función.

    function appendDisclaimerOnSend(event) { 
  // Calls the getTypeAsync method and passes its returned value to the options.coercionType parameter of the appendOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    }, 
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }

    // Sets the disclaimer to be appended to the body of the message on send.
    const bodyFormat = asyncResult.value;
    const disclaimer =
      '<p style = "color:blue"> <i>This and subsequent emails on the same topic are for discussion and information purposes only. Only those matters set out in a fully executed agreement are legally binding. This email may contain confidential information and should not be shared with any third party without the prior written agreement of Contoso. If you are not the intended recipient, take no action and contact the sender immediately.<br><br>Contoso Limited (company number 01624297) is a company registered in England and Wales whose registered office is at Contoso Campus, Thames Valley Park, Reading RG6 1WG</i></p>';  

    Office.context.mailbox.item.body.appendOnSendAsync(
      disclaimer,
      {
        asyncContext: asyncResult.asyncContext,
        coercionType: bodyFormat
      },
      (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        console.log("The disclaimer will be appended when the mail item is sent.");
        asyncResult.asyncContext.completed();
      }
    );
  });
}

  2. Guarde los cambios.

Registro de las funciones de JavaScript

  1. En el mismo archivo commands.js , inserte lo siguiente después de la appendDisclaimerOnSend función. Estas llamadas asignan el nombre de función especificado en el manifiesto a su homólogo de JavaScript. La ubicación del nombre de la función en el manifiesto varía en función del tipo de manifiesto que use el complemento.

  • Manifiesto de solo complemento: nombre de función especificado en el <elemento FunctionName> .

  • Manifiesto unificado para Microsoft 365: nombre de función especificado en la propiedad "id" de los objetos de la matriz "extensions.runtimes.actions".

    Office.actions.associate("prependHeaderOnSend", prependHeaderOnSend);
Office.actions.associate("appendDisclaimerOnSend", appendDisclaimerOnSend);
  1. Guarde los cambios.

Pruébelo

  1. Ejecute el siguiente comando en el directorio principal del proyecto. Al ejecutar este comando, el servidor web local se iniciará si aún no se está ejecutando y el complemento se transferirá de forma local.

    npm start

    Nota:

    Si el complemento no se ha descargado de forma local automáticamente, siga las instrucciones de Transferencia local de complementos de Outlook para realizar pruebas para transferir manualmente el complemento en Outlook.

  2. Cree un mensaje y agréguese a la línea Para .

  3. (Opcional) Escriba texto en el cuerpo del mensaje.

  4. En el menú de la cinta de opciones o de desbordamiento, seleccione Encabezado de anteposición.

  5. En el menú de la cinta de opciones o de desbordamiento, seleccione Agregar declinación de responsabilidades.

  6. Envíe el mensaje y ábralo desde la carpeta Bandeja de entrada o Elementos enviados para ver el contenido insertado.

    Ejemplo de un mensaje enviado con el encabezado Contoso antepuesto y la declinación de responsabilidades anexada a su cuerpo.

    Sugerencia

    Dado que el contenido solo se antepone o anexa una vez que se envía el mensaje, el remitente solo podrá ver el contenido agregado desde su bandeja de entrada o la carpeta Elementos enviados . Si necesita que el remitente vea el contenido agregado antes de enviar el mensaje, consulte Insertar datos en el cuerpo al redactar una cita o mensaje en Outlook.

  7. Si desea detener el servidor web local y desinstalar el complemento, siga las instrucciones aplicables:

    • Para detener el servidor, ejecute el siguiente comando. Si usó npm start, el siguiente comando también debe desinstalar el complemento.

      npm stop

    • Si descargó manualmente el complemento de forma local, consulte Eliminación de un complemento cargado localmente.

Revisión del comportamiento y las limitaciones de las características

A medida que implemente prepend-on-send y append-on-send en el complemento, tenga en cuenta lo siguiente.

  • Prepend-on-send y append-on-send solo se admiten en el modo de redacción.

  • La cadena que se va a anteponer o anexar no debe superar los 5000 caracteres.

  • Html no se puede anteponer ni anexar a un cuerpo de texto sin formato de un mensaje o cita. Sin embargo, el texto sin formato se puede agregar a un cuerpo con formato HTML de un mensaje o cita.

  • Cualquier formato aplicado al contenido antepuesto o anexado no afecta al estilo del resto del cuerpo del elemento de correo.

  • Prepend-on-send y append-on-send no se pueden implementar en el mismo complemento que implementa la característica de envío. Como alternativa, considere la posibilidad de implementar alertas inteligentes en su lugar.

  • Al implementar alertas inteligentes en el mismo complemento, las operaciones prepend-on-send y append-on-send se producen antes de las operaciones del OnMessageSend controlador de eventos y OnAppointmentSend .

  • Si varios complementos activos usan prepend-on-send o append-on-send, el orden del contenido que se va a insertar depende del orden en que se ejecutó el complemento. Para anteponer al envío, el contenido del complemento que se ejecuta por última vez aparece en la parte superior del cuerpo del elemento de correo antes del contenido anteriormente antepuesto. Para anexar al envío, el contenido del complemento que se ejecuta por última vez aparece en la parte inferior del cuerpo del elemento de correo después del contenido anexado anteriormente.

  • Los escenarios de delegación y buzón compartido se admiten siempre que el complemento que implementa prepend-on-send o append-on-send esté habilitado en el buzón compartido o en la cuenta del propietario.

Solución de problemas del complemento

Si se produce un error al implementar las características prepend-on-send y append-on-send, consulte la tabla siguiente para obtener instrucciones.

Error Descripción Solución
DataExceedsMaximumSize El contenido que se va a anexar o anteponer tiene más de 5000 caracteres. Acorte la cadena que pasa al data parámetro de la prependOnSendAsync llamada o appendOnSendAsync .
InvalidFormatError El cuerpo del mensaje o de la cita está en formato de texto sin formato, pero el coercionType objeto pasado al prependOnSendAsync método o appendOnSendAsync está establecido en Office.CoercionType.Html. Solo se puede insertar texto sin formato en un cuerpo de texto sin formato de un mensaje o cita. Para comprobar el formato del elemento de correo que se va a componer, llame a Office.context.mailbox.item.body.getTypeAsyncy, a continuación, pase su valor devuelto a la prependOnSendAsync llamada o appendOnSendAsync .

Vea también