Compartir a través de

Activación del complemento de Outlook en varios mensajes

  • Artículo

Con la característica de selección múltiple de elementos, el complemento de Outlook ahora puede activar y realizar operaciones en varios mensajes seleccionados de una sola vez. Algunas operaciones, como cargar mensajes en el sistema de administración de relaciones con el cliente (CRM) o categorizar numerosos elementos, ahora se pueden completar fácilmente con un solo clic.

En las secciones siguientes se muestra cómo configurar el complemento para recuperar la línea de asunto y la dirección de correo electrónico del remitente de varios mensajes en modo de lectura.

Nota:

La compatibilidad con la característica de selección múltiple de elementos se introdujo en el conjunto de requisitos 1.13, con propiedades de elementos adicionales ahora disponibles en conjuntos de requisitos posteriores. Vea clientes y plataformas compatibles con este conjunto de requisitos.

Configurar el entorno

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

Configuración del manifiesto

  1. En el editor de código que prefiera, abra el proyecto de inicio rápido de Outlook que creó.

  2. Abra el archivo manifest.json ubicado en la raíz del proyecto.

  3. En la matriz "authorization.permissions.resourceSpecific", cambie el valor de la propiedad "name" a "Mailbox.ReadWrite.User". Debería tener un aspecto similar al siguiente cuando haya terminado.

    "authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "Mailbox.ReadWrite.User",
                "type": "Delegated"
            }
        ]
    }
},

  4. En el primer objeto de la matriz "extensions.runtimes", realice los siguientes cambios.

    1. Cambie la propiedad "requirements.capabilities.minVersion" a "1.13".
    2. En el mismo objeto "actions", agregue la propiedad "supportsNoItemContext" y establézcala en true.
    3. En el mismo objeto "actions", agregue la propiedad "multiselect" y establézcala en true.

    El código debe tener un aspecto similar al siguiente después de realizar los cambios.

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "TaskPaneRuntimeShow",
                "type": "openPage",
                "pinnable": false,
                "view": "dashboard",
                "supportsNoItemContext": true,
                "multiselect": true
            }
        ]
    },
    ...
]

  5. Elimine el segundo objeto de la matriz "extensions.runtimes", cuyo "id" es "CommandsRuntime".

  6. En la matriz "extensions.ribbons.tabs.controls", elimine el segundo objeto, cuyo "id" es "ActionButton".

  7. Guarde los cambios.

Nota:

Si activa la característica de selección múltiple de elementos en el complemento, el complemento admitirá automáticamente la característica de contexto sin elemento , incluso si no está configurada explícitamente en el manifiesto. Para obtener más información sobre el comportamiento de anclaje del panel de tareas en complementos de selección múltiple, consulte Anclaje del panel de tareas en complementos de selección múltiple.

Configuración del panel de tareas

La selección múltiple de elementos se basa en el evento SelectedItemsChanged para determinar cuándo se seleccionan o anulan la selección de los mensajes. Este evento requiere una implementación del panel de tareas.

  1. En la carpeta ./src/taskpane , abra taskpane.html.

  2. En el elemento body<>, reemplace todo <el elemento principal> por el marcado siguiente.

    <main id="app-body" class="ms-welcome__main">
    <h2 class="ms-font-l">Get information about each selected message</h2>
    <ul id="selected-items"></ul>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Get information</span>
    </div>
</main>

  3. Solo para Outlook clásico en Windows. Reemplace el elemento de script existente por el marcado siguiente. Hace referencia a la versión preliminar de la API de JavaScript de Office.

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>

    Nota:

    La versión preliminar de la API de JavaScript de Office se usa porque en este tutorial se implementan los loadItemByIdAsync métodos y unloadAsync , que están actualmente en versión preliminar. Si el complemento de selección múltiple no implementa estos métodos, use https://appsforoffice.microsoft.com/lib/1/hosted/office.js en su lugar. Para obtener más información, consulte Referencia a la biblioteca de API de JavaScript de Office.

  4. Guarde los cambios.

Implementación de un controlador para el evento SelectedItemsChanged

Para alertar al complemento cuando se produzca el SelectedItemsChanged evento, debe registrar un controlador de eventos mediante el addHandlerAsync método .

  1. En la carpeta ./src/taskpane , abra taskpane.js.

  2. Reemplace la Office.onReady() función por lo siguiente:

    let list;

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("run").onclick = run;
    list = document.getElementById("selected-items");

    // Register an event handler to identify when messages are selected.
    Office.context.mailbox.addHandlerAsync(Office.EventType.SelectedItemsChanged, run, (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      console.log("Event handler added.");
    });
  }
});

  3. Guarde los cambios.

Obtención de propiedades y ejecución de operaciones en mensajes seleccionados

Ahora que ha registrado un controlador de eventos, el complemento ahora puede obtener propiedades o ejecutar operaciones en varios mensajes seleccionados. Hay dos maneras de procesar los mensajes seleccionados. El uso de cada opción depende de las propiedades y operaciones que necesite para su escenario.

  • Llame al método getSelectedItemsAsync para obtener las siguientes propiedades.

    • Boolean de datos adjuntos
    • Identificador de conversación
    • Identificador de mensaje de Internet
    • Id. de elemento
    • Modo de elemento (Read o Compose)
    • Tipo de elemento (Message es el único tipo admitido en este momento)
    • Línea del asunto

  • Llame al método loadItemByIdAsync (versión preliminar) para obtener propiedades que no proporcionan getSelectedItemsAsync o para ejecutar operaciones en los mensajes seleccionados. El loadItemByIdAsync método carga un mensaje seleccionado a la vez mediante el identificador de Exchange Web Services (EWS) del mensaje. Para obtener los identificadores de EWS de los mensajes seleccionados, se recomienda llamar a getSelectedItemsAsync. Después de procesar un mensaje seleccionado mediante loadItemByIdAsync, debe llamar al método unloadAsync (versión preliminar) antes de llamar a loadItemByIdAsync en otro mensaje seleccionado.

    Sugerencia

    Antes de usar el loadItemByIdAsync método , determine si ya puede acceder a las propiedades que necesita mediante getSelectedItemsAsync. Si puede, no es necesario llamar loadItemByIdAsynca .

En el ejemplo siguiente se implementan los getSelectedItemsAsync métodos y loadItemByIdAsync para obtener la línea de asunto y la dirección de correo electrónico del remitente de cada mensaje seleccionado.

Nota:

El loadItemByIdAsync método está actualmente en versión preliminar en Outlook clásico en Windows. Para obtener una vista previa de esta API, instale la versión 2405 (compilación 17606.10000) o posterior. A continuación, únase al programa Microsoft 365 Insider y seleccione la opción Canal beta .

  1. En taskpane.js, reemplace la función existente run por el código siguiente.

    export async function run() {
  // Clear the list of previously selected messages, if any.
  clearList(list);

  // Get the subject line and sender's email address of each selected message and log it to a list in the task pane.
  Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log(asyncResult.error.message);
      return;
    }

    const selectedItems = asyncResult.value;
    getItemInfo(selectedItems);
  });
}

// Gets the subject line and sender's email address of each selected message.
async function getItemInfo(selectedItems) {
  for (const item of selectedItems) {
    addToList(item.subject);
    // The loadItemByIdAsync method is currently only available to preview in classic Outlook on Windows.
    if (Office.context.diagnostics.platform === Office.PlatformType.PC) {
      await getSenderEmailAddress(item);
    }
  }
}

// Gets the sender's email address of each selected message.
async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
      }

      const loadedItem = result.value;
      const sender = loadedItem.from.emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        resolve();
      });
    });
  });
}

// Clears the list in the task pane.
function clearList(list) {
  while (list.firstChild) {
    list.removeChild(list.firstChild);
  }
}

// Adds an item to a list in the task pane.
function addToList(item) {
  const listItem = document.createElement("li");
  listItem.textContent = item;
  list.appendChild(listItem);
}

// Appends data to the last item of the list in the task pane.
function appendToListItem(data) {
  const listItem = list.lastChild;
  listItem.textContent += ` (${data})`;
}

  2. Guarde los cambios.

Pruébelo

  1. Desde un terminal, ejecute el código siguiente en el directorio raíz del proyecto. Esto inicia el servidor web local y carga localmente el complemento.

    npm start

    Sugerencia

    Si el complemento no se carga de forma local automáticamente, siga las instrucciones de Transferencia local de complementos de Outlook para realizar pruebas a fin de transferirlo de forma local manualmente en Outlook.

  2. En Outlook, asegúrese de que el panel de lectura está habilitado. Para habilitar el panel de lectura, consulte Uso y configuración del panel de lectura para obtener una vista previa de los mensajes.

  3. Vaya a la bandeja de entrada y elija varios mensajes manteniendo presionada la tecla Ctrl mientras selecciona mensajes.

  4. Seleccione Mostrar panel de tareas. La ubicación del complemento varía según el cliente de Outlook. Para obtener instrucciones, vea Usar complementos en Outlook.

  5. En el panel de tareas, seleccione Obtener información. En el panel de tareas se muestra una lista de las líneas de asunto y las direcciones de correo electrónico del remitente de los mensajes seleccionados.

    Una lista de ejemplo de líneas de asunto recuperadas de varios mensajes seleccionados.

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

Comportamiento y limitaciones de selección múltiple de elementos

La selección múltiple de elementos solo admite mensajes dentro de un buzón de Exchange en los modos de lectura y redacción. Un complemento de Outlook solo se activa en varios mensajes si se cumplen las condiciones siguientes.

  • Los mensajes deben seleccionarse de un buzón de Exchange a la vez. No se admiten buzones que no sean de Exchange.
  • Los mensajes deben seleccionarse de una carpeta de buzón a la vez. Un complemento no se activa en varios mensajes si se encuentran en carpetas diferentes, a menos que la vista Conversaciones esté habilitada. Para obtener más información, consulte Selección múltiple en conversaciones.
  • Un complemento debe implementar un panel de tareas para detectar el SelectedItemsChanged evento.
  • El panel de lectura de Outlook debe estar habilitado. Una excepción a esto es si la característica de selección múltiple de elementos está habilitada a través de la característica de contexto sin elemento en el manifiesto. Para obtener más información, vea Activar el complemento de Outlook sin el panel de lectura habilitado o un mensaje seleccionado.
  • Se puede seleccionar un máximo de 100 mensajes a la vez.
  • El loadItemByIdAsync método solo procesa un mensaje seleccionado a la vez. No olvide llamar unloadAsync a una vez loadItemByIdAsync que haya terminado de procesar el mensaje. De este modo, el complemento puede cargar y procesar el siguiente mensaje seleccionado.
  • Normalmente, solo puede ejecutar operaciones get en un mensaje seleccionado que se carga mediante el loadItemByIdAsync método . Sin embargo, la administración de las categorías de un mensaje cargado es una excepción. Puede agregar, obtener y quitar categorías de un mensaje cargado.
  • El loadItemByIdAsync método se admite en los complementos de panel de tareas y comandos de función. Este método no se admite en complementos de activación basados en eventos.

Nota:

Las invitaciones y respuestas a reuniones se consideran mensajes, no citas y, por lo tanto, se pueden incluir en una selección.

Selección múltiple en conversaciones

La selección múltiple de elementos admite conversaciones para ver si está habilitado en el buzón de correo o en carpetas específicas. En la tabla siguiente se describen los comportamientos esperados cuando las conversaciones se expanden o contraen, cuando se selecciona el encabezado de conversación y cuando los mensajes de conversación se encuentran en una carpeta diferente a la que se ve actualmente.

Selección Vista de conversación expandida Vista de conversación contraída
El encabezado de conversación está seleccionado Si el encabezado de conversación es el único elemento seleccionado, no se activa un complemento compatible con la selección múltiple. Sin embargo, si también se seleccionan otros mensajes que no son de encabezado, el complemento solo se activará en ellos y no en el encabezado seleccionado. El comportamiento varía en función del cliente de Outlook.

Outlook en Windows (clásico) y en Mac:
El mensaje más reciente (es decir, el primer mensaje de la pila de conversaciones) se incluye en la selección del mensaje.

Si el mensaje más reciente de la conversación se encuentra en otra carpeta de la que está actualmente en vista, el mensaje posterior de la pila ubicada en la carpeta actual se incluye en la selección.

Outlook en la Web y nueva Outlook en Windows:
Se seleccionan todos los mensajes de la pila de conversaciones. Esto incluye los mensajes de la conversación que se encuentran en carpetas distintas de la que se está viendo actualmente.
Varios mensajes seleccionados en una pila de conversaciones se encuentran en la misma carpeta que el que está actualmente en vista. Todos los mensajes elegidos en la misma conversación se incluyen en la selección. No procede. Debe expandir la pila de conversaciones para seleccionar varios mensajes de ella.
Varios mensajes seleccionados en una pila de conversaciones se encuentran en carpetas diferentes a las que se encuentran actualmente en la vista. Todos los mensajes elegidos en la misma conversación se incluyen en la selección. No procede. Debe expandir la pila de conversaciones para seleccionar varios mensajes de ella.

Nota:

En todos los clientes de Outlook, no puede seleccionar varios mensajes que pertenezcan a conversaciones diferentes. Si expande una conversación diferente mientras se expande otra conversación, la vista de la conversación expandida se contrae y se anula la selección de los mensajes seleccionados. Sin embargo, puede seleccionar varios mensajes de la misma conversación expandida y mensajes que no forman parte de ninguna conversación al mismo tiempo.

Anclaje del panel de tareas en complementos de selección múltiple

En Outlook en la Web y en el nuevo Outlook en Windows, cuando se abre el panel de tareas de un complemento de selección múltiple, se ancla automáticamente al cliente de Outlook. Permanece anclado incluso cuando un usuario cambia a un elemento de correo diferente o selecciona el icono de anclar en el panel de tareas. El panel de tareas solo se puede cerrar seleccionando el botón Cerrar del panel de tareas.

Por el contrario, en Outlook en Windows (clásico) y en Mac, el panel de tareas no se ancla automáticamente y se cierra cuando un usuario cambia a otro elemento de correo.

Pasos siguientes

Ahora que ha habilitado el complemento para que funcione en varios mensajes seleccionados, puede ampliar las funcionalidades del complemento y mejorar aún más la experiencia del usuario. Explore la realización de operaciones más complejas mediante los identificadores de elemento de los mensajes seleccionados con servicios, como Microsoft Graph.

Recursos adicionales