Usar la API de cuadros de diálogo de Office en los complementos de Office

Use la API de diálogo de Office para abrir cuadros de diálogo en el complemento de Office. En este artículo se proporciona ayuda para utilizar la API de cuadros de diálogo en su complemento de Office. Considere la posibilidad de abrir un cuadro de diálogo desde un panel de tareas, un complemento de contenido o un comando de complemento para realizar las siguientes tareas.

• Inicie sesión en un usuario con un recurso como Google, Facebook o la identidad de Microsoft. Para obtener más información, consulte Autenticación con la API de cuadro de diálogo de Office.
• Proporcionar más espacio en pantalla, o incluso una pantalla completa, para algunas tareas en su complemento.
• Hospedar un vídeo que sería demasiado pequeño si se limitase a un panel de tareas.
• Mostrar una pantalla de error, progreso o entrada.

La siguiente imagen muestra un ejemplo de un cuadro de diálogo.

El cuadro de diálogo siempre se abre en el centro de la pantalla. El usuario puede moverlo y cambiarle el tamaño. La ventana no esmodal : un usuario puede seguir interactuando con el documento de la aplicación de Office y con la página del panel de tareas, si hay uno.

Abrir un cuadro de diálogo desde una página host

Las API de JavaScript para Office incluyen un objeto Dialog y dos funciones en el espacio de nombres Office.context.ui.

Para abrir un cuadro de diálogo, el código, normalmente una página de un panel de tareas, llama al método displayDialogAsync y pasa la dirección URL del recurso que desea abrir. La página en la que se llama a este método se conoce como "página host". Por ejemplo, si llama a este método en script en index.html en un panel de tareas, index.html es la página host del cuadro de diálogo que abre el método.

El recurso que se abre en el cuadro de diálogo suele ser una página, pero puede ser un método de controlador en una aplicación de MVC, una ruta, un método de servicio web o cualquier otro recurso. En este artículo, "página" o "sitio web" hace referencia al recurso del cuadro de diálogo. El código siguiente es un ejemplo sencillo.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html");

• La URL utiliza el protocolo HTTPS. Este protocolo es obligatorio para todas las páginas cargadas en un cuadro de diálogo, no solo para la primera página cargada.
• El dominio del cuadro de diálogo es el mismo que el dominio de la página host, que puede ser la página en un panel de tareas o el archivo de función de un comando de complementos. La página, el método de controlador u otro recurso que pase al displayDialogAsync método debe estar en el mismo dominio que la página host.

Una vez que se carga la primera página (u otro recurso), un usuario puede usar vínculos u otra interfaz de usuario para navegar a cualquier sitio web (u otro recurso) que use HTTPS. También puede diseñar la primera página para redirigirla inmediatamente a otro sitio.

De forma predeterminada, el cuadro de diálogo ocupa el 80 % del alto y el ancho de la pantalla del dispositivo, pero puede establecer diferentes porcentajes pasando un objeto de configuración al método , como se muestra en el ejemplo siguiente.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Para obtener un complemento de ejemplo que haga esto, vea Tutorial de Excel: Completado. Para obtener más ejemplos que usan displayDialogAsync, consulte Ejemplos de código.

Establezca ambos valores al 100 % para obtener lo que es una experiencia de pantalla completa. El máximo efectivo es del 99,5 %, y la ventana todavía se puede mover y se puede cambiar de tamaño.

Solo se puede abrir un cuadro de diálogo desde una ventana host. Al intentar abrir otro cuadro de diálogo se genera un error. Por ejemplo, si un usuario abre un cuadro de diálogo desde un panel de tareas, no puede abrir un segundo cuadro de diálogo desde una página diferente en el panel de tareas. Sin embargo, cuando se abre un cuadro de diálogo desde un comando de complementos, el comando abre un nuevo archivo HTML (aunque no se vea) cada vez que se selecciona. Este proceso crea una nueva ventana host (no se ve), por lo que cada ventana puede iniciar su propio cuadro de diálogo. Para más información, consulte Errores desde displayDialogAsync.

Aprovechar las ventajas de la opción de rendimiento en Office en la Web

La displayInIframe propiedad es una propiedad adicional en el objeto de configuración que se pasa a displayDialogAsync. Al establecer esta propiedad true en y el complemento se ejecuta en un documento abierto en Office en la Web, el cuadro de diálogo se abre como un iframe flotante en lugar de una ventana independiente. Este enfoque hace que el cuadro de diálogo se abra más rápido. En el ejemplo siguiente se muestra cómo usar esta propiedad.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20, displayInIframe: true });

El valor predeterminado es false, que equivale a omitir la propiedad por completo. Si el complemento no se ejecuta en Office en la Web, se omite la displayInIframe propiedad .

Enviar información desde el cuadro de diálogo a la página host

El código del cuadro de diálogo usa la función messageParent para enviar un mensaje de cadena a la página host. La cadena puede ser una palabra, una oración, un blob XML, un JSON con cadena o cualquier otra cosa que se pueda serializar en una cadena o convertirla en una cadena. Para usar el messageParent método , el cuadro de diálogo debe inicializar primero la API de JavaScript de Office.

En el ejemplo siguiente se muestra cómo inicializar Office JS y enviar un mensaje a la página host.

Office.onReady(() => {
   // Add any initialization code for your dialog here.
});

// Called when dialog signs in the user.
function userSignedIn() {
    Office.context.ui.messageParent(true.toString());
}

En el ejemplo siguiente se muestra cómo devolver una cadena JSON que contiene información de perfil.

function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

La messageParent función es una de las dos API de Office JS a las que puede llamar en el cuadro de diálogo. La otra API de JS a la que puede llamar en el cuadro de diálogo es Office.context.requirements.isSetSupported. Para obtener información al respecto, vea Especificar aplicaciones de Office y requisitos de API. Sin embargo, en el cuadro de diálogo, esta API no se admite en Outlook 2016 perpetuas con licencia por volumen (es decir, la versión de MSI).

Debe configurar la página host para recibir el mensaje. Agregue un parámetro de devolución de llamada a la llamada original de displayDialogAsync. La devolución de llamada asigna un controlador al evento DialogMessageReceived. En el ejemplo siguiente, se muestra cómo hacerlo.

let dialog; // Declare dialog as global for use in later functions.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

Office pasa un objeto AsyncResult a la devolución de llamada. Representa el resultado del intento de abrir el cuadro de diálogo. No representa el resultado de ningún evento en el cuadro de diálogo. Para obtener más información sobre esta distinción, consulte Tratamiento de errores y eventos.

• La propiedad value de asyncResult se establece en un objeto Dialog, que existe en la página host, no en el contexto de ejecución del cuadro de diálogo.
• La processMessage función controla el evento. Puede ponerle el nombre que desee.
• La variable dialog se declara en un ámbito más amplio que la devolución de llamada porque también se le hace referencia en processMessage.

En el ejemplo siguiente se muestra un controlador simple para el DialogMessageReceived evento.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

Office pasa el objeto arg al controlador. Su message propiedad es la cadena enviada por la llamada de messageParent en el cuadro de diálogo. En este ejemplo, se trata de una representación stringified del perfil de un usuario desde un servicio, como una cuenta de Microsoft o Google, por lo que se deserializa de nuevo en un objeto con JSON.parse. No se muestra la showUserName implementación. Puede mostrar un mensaje de bienvenida personalizado en el panel de tareas.

Cuando se completa la interacción del usuario con el cuadro de diálogo, el controlador de mensajes debe cerrar el cuadro de diálogo, tal y como se muestra en este ejemplo.

function processMessage(arg) {
    dialog.close();
    // Add code to process the message here.
}

El objeto dialog debe ser el mismo que el devuelto por la llamada de displayDialogAsync. Declare el dialog objeto como una variable global. O bien, puede limitar el dialog objeto a la displayDialogAsync llamada con una función de devolución de llamada anónima, como se muestra en el ejemplo siguiente. En el ejemplo, processMessage no es necesario cerrar el cuadro de diálogo, ya que se llama al close método en la función de devolución de llamada anónima.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
      }
    );

Si el complemento necesita abrir una página diferente del panel de tareas después de recibir el mensaje, use el window.location.replace método (o window.location.href) como última línea del controlador. En el ejemplo siguiente, se muestra cómo hacerlo.

function processMessage(arg) {
    // Add code to process the message here.
    window.location.replace("/newPage.html");
    // Alternatively, use the following:
    // window.location.href = "/newPage.html";
}

Para obtener un ejemplo de un complemento que hace esto, consulte la muestra Insertar gráficos de Excel con Microsoft Graph en un complemento de PowerPoint.

Mensajería condicional

Debido a que puede enviar varias llamadas messageParent desde el cuadro de diálogo, pero solo tiene un controlador en la página host para el evento DialogMessageReceived, el controlador debe utilizar la lógica condicional para distinguir diferentes mensajes. Por ejemplo, si el cuadro de diálogo solicita a un usuario que inicie sesión en un proveedor de identidades, como una cuenta de Microsoft o Google, envía el perfil del usuario como un mensaje. Si se produce un error en la autenticación, el cuadro de diálogo envía información de error a la página host, como en el ejemplo siguiente.

if (loginSuccess) {
    const userProfile = getProfile();
    const messageObject = { messageType: "signinSuccess", profile: userProfile };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    const errorDetails = getError();
    const messageObject = { messageType: "signinFailure", error: errorDetails };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Sobre el ejemplo anterior, tenga en cuenta lo siguiente:

• La loginSuccess variable se inicializa leyendo la respuesta HTTP del proveedor de identidades.
• No se muestra la implementación de las getProfile funciones y getError . Cada uno obtiene datos de un parámetro de consulta o del cuerpo de la respuesta HTTP.
• Se envían objetos anónimos de diferentes tipos dependiendo de si el inicio de sesión ha sido correcto o no. Ambos tienen una propiedad messageType, pero uno tiene una propiedad profile y el otro tiene una propiedad error.

El código del controlador en la página host utiliza el valor de la propiedad messageType para crear una rama como se muestra en el ejemplo siguiente. Tenga en cuenta que la función showUserName es la misma que en el ejemplo anterior y que la función showNotification muestra el error en la interfaz de usuario de la página host.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

No se muestra la showNotification implementación. Podría mostrar el estado en una barra de notificaciones en el panel de tareas.

Mensajería entre dominios en el entorno de ejecución del host

Una vez abierto el cuadro de diálogo, el cuadro de diálogo o el entorno de ejecución primario pueden desplazarse fuera del dominio del complemento. Si ocurre alguna de estas cosas, se produce un error en una llamada a a messageParent menos que el código especifique el dominio del entorno de ejecución primario. Agregue un parámetro DialogMessageOptions a la llamada de messageParent para especificar el dominio. Este objeto tiene una targetOrigin propiedad que especifica el dominio al que se debe enviar el mensaje. Si no usa el parámetro , Office asume que el destino es el mismo dominio que el cuadro de diálogo hospeda actualmente.

En el ejemplo siguiente se muestra cómo usar messageParent para enviar un mensaje entre dominios.

Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });

Si el mensaje no incluye datos confidenciales, puede establecer en targetOrigin "*", lo que permite que se envíe a cualquier dominio. En el ejemplo siguiente, se muestra cómo hacerlo.

Office.context.ui.messageParent("Some message", { targetOrigin: "*" });

Pasar información al cuadro de diálogo

El complemento puede enviar mensajes desde la página host a un cuadro de diálogo mediante Dialog.messageChild.

Uso messageChild() desde la página host

Al llamar a la API de diálogo de Office para abrir un cuadro de diálogo, devuelve un objeto Dialog . Asigne este objeto a una variable con ámbito global para que pueda hacer referencia a él desde otras funciones. En el ejemplo siguiente, se muestra cómo hacerlo.

let dialog; // Declare as global variable.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html",
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

function processMessage(arg) {
    dialog.close();

    // Add code to process the message here.

}

Este Dialog objeto tiene un método messageChild que envía cualquier cadena, incluidos los datos stringified, al cuadro de diálogo. Este método genera un DialogParentMessageReceived evento en el cuadro de diálogo. El código debe controlar este evento, como se muestra en la sección siguiente.

Considere un escenario en el que la interfaz de usuario del cuadro de diálogo está relacionada con la hoja de cálculo de Excel activa actualmente y la posición de esa hoja de cálculo en relación con las demás hojas de cálculo. En el ejemplo siguiente, worksheetPropertiesChanged envía las propiedades de la hoja de cálculo activa al cuadro de diálogo. Los datos se stringified para que se puedan pasar a messageChild.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

Controlar dialogParentMessageReceived en el cuadro de diálogo

En JavaScript del cuadro de diálogo, registre un controlador para el DialogParentMessageReceived evento mediante el método UI.addHandlerAsync . Normalmente, se registra el controlador en la función Office.onReady o Office.initialize, como se muestra en el ejemplo siguiente. (Más adelante en este artículo se incluye un ejemplo más sólido).

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(Office.EventType.DialogParentMessageReceived,onMessageFromParent);
});

A continuación, defina el onMessageFromParent controlador. El código siguiente continúa el ejemplo de la sección anterior. Tenga en cuenta que Office pasa un argumento al controlador y que la message propiedad del objeto argument contiene la cadena de la página host. En este ejemplo, el mensaje se vuelve a convertir en un objeto y jQuery se usa para establecer el encabezado superior del cuadro de diálogo para que coincida con el nuevo nombre de hoja de cálculo.

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

Se recomienda comprobar que el controlador está registrado correctamente. Para ello, pase una devolución de llamada al addHandlerAsync método . Esta devolución de llamada se ejecuta cuando se completa el intento de registrar el controlador. Use el controlador para registrar o mostrar un error si el controlador no se registró correctamente. En el ejemplo siguiente, se muestra cómo hacerlo. Tenga en cuenta que reportError es una función, no definida aquí, que registra o muestra el error.

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        reportError(asyncResult.error.message);
    }
}

Mensajería condicional desde la página primaria al cuadro de diálogo

Dado que la página host puede realizar varias messageChild llamadas, pero el cuadro de diálogo solo tiene un controlador para el DialogParentMessageReceived evento, el controlador debe usar lógica condicional para distinguir mensajes diferentes. Puede estructurar esta lógica condicional de forma que sea exactamente paralela a cómo estructura la mensajería condicional cuando el cuadro de diálogo envía un mensaje a la página host, como se describe en Mensajería condicional.

Mensajería entre dominios en el tiempo de ejecución del cuadro de diálogo

Una vez abierto el cuadro de diálogo, el cuadro de diálogo o el entorno de ejecución primario pueden desplazarse fuera del dominio del complemento. Si ocurre alguna de estas cosas, las llamadas a producirán un error a messageChild menos que el código especifique el dominio del tiempo de ejecución del cuadro de diálogo. Agregue un parámetro DialogMessageOptions a la llamada de messageChild para especificar el dominio. Este objeto tiene una targetOrigin propiedad que especifica el dominio al que se debe enviar el mensaje. Si no usa el parámetro , Office asume que el destino es el mismo dominio que el entorno de ejecución primario hospeda actualmente.

En el ejemplo siguiente se muestra cómo usar messageChild para enviar un mensaje entre dominios.

dialog.messageChild(messageToDialog, { targetOrigin: "https://resource.contoso.com" });

Si el mensaje no incluye datos confidenciales, puede establecer en targetOrigin "*", lo que permite que se envíe a cualquier dominio. En el ejemplo siguiente se muestra cómo establecer .targetOrigin

dialog.messageChild(messageToDialog, { targetOrigin: "*" });

El manifiesto del complemento especifica dominios de confianza. En el manifiesto unificado para Microsoft 365, especifique este dominio en la propiedad "validDomains". En el manifiesto de solo complemento, especifique este dominio en el <AppDomains> elemento .

Pero el entorno de ejecución que hospeda el cuadro de diálogo no puede acceder al manifiesto y, por tanto, determinar si el dominio del que procede el mensaje es de confianza. Debe usar el DialogParentMessageReceived controlador para determinar esto. El objeto que se pasa al controlador contiene el dominio que se hospeda actualmente en el elemento primario como su origin propiedad. En el ejemplo siguiente se muestra cómo usar la propiedad .

function onMessageFromParent(arg) {
    if (arg.origin === "https://addin.fabrikam.com") {
        // Process the message.
    } else {
        // Signal the parent page to close the dialog.
        const messageObject = { messageType: "untrustedDomain" };
        Office.context.ui.messageParent(messageObject);
    }
}

Por ejemplo, el código podría usar la función Office.onReady o Office.initialize para almacenar una matriz de dominios de confianza en una variable global. A arg.origin continuación, se podría comprobar la propiedad en esa lista en el controlador.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
"My trusted domain"="https://www.contoso.com"
"Another trusted domain"="https://fabrikam.com"

Cerrar el cuadro de diálogo

Puede agregar un botón al cuadro de diálogo que lo cierra. Para ello, el controlador de eventos click del botón debe usar messageParent para indicar a la página host que se ha hecho clic en el botón. En el ejemplo siguiente se muestra cómo implementar esta funcionalidad.

function closeButtonClick() {
    const messageObject = { messageType: "dialogClosed" };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Controlador de página host para DialogMessageReceived llamadas dialog.close, como se muestra en este ejemplo. (Consulte ejemplos anteriores que muestran cómo se inicializa el objeto dialog).

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Incluso si no agrega su propia interfaz de usuario de cuadro de diálogo de cierre, un usuario final puede cerrar el cuadro de diálogo eligiendo la X en la esquina superior derecha. Esta acción activa el evento DialogEventReceived. Si el panel host necesita saber cuándo se produce este evento, debe declarar un controlador para este evento. Para obtener más información, vea Errores y eventos en el cuadro de diálogo.

No usar window.open

No use el método de explorador window.open() estándar para abrir diálogos o ventanas emergentes en complementos de Office. El window.open() método no funciona de forma confiable en los distintos controles de explorador y vista web en los que se ejecutan los complementos de Office. Es posible que encuentre los siguientes problemas con window.open().

• No funciona en contextos de iframe: cuando el complemento se ejecuta en Office en la Web, el panel de tareas está dentro de un iframe. Por motivos de seguridad, muchos exploradores bloquean o restringen window.open() gravemente las llamadas desde iframes.
• Bloqueado por bloqueadores de elementos emergentes: los bloqueadores emergentes basados en explorador bloquean window.open() las llamadas y el comportamiento varía entre los exploradores.
• Comportamiento de vista web incoherente: los controles de vista web insertados que usan las aplicaciones de Office de escritorio controlan window.open() de forma diferente a los exploradores completos, lo que da lugar a un comportamiento impredecible.
• Ninguna garantía multiplataforma: incluso si window.open() funciona en una plataforma (como el escritorio de Windows), podría producir un error completamente en otra plataforma (por ejemplo, Office en la Web o Mac).

Use siempre la API de cuadros de diálogo de Office en su lugar. La API de diálogo de Office (Office.context.ui.displayDialogAsync) está diseñada específicamente para funcionar de forma coherente en todas las plataformas de Office y entornos en tiempo de ejecución. Proporciona una funcionalidad de diálogo confiable que funciona tanto si el complemento se ejecuta en un explorador, un control de vista web o un iframe.

Para abrir direcciones URL externas en una ventana del explorador independiente (no para la autenticación o el intercambio de datos con el complemento), use el Office.context.ui.openBrowserWindow(url) método en su lugar, donde url suele ser una dirección URL HTTPS.

Ejemplos de código

Todos los ejemplos siguientes usan displayDialogAsync. Algunos tienen servidores basados en NodeJS y otros tienen servidores ASP.NET/IIS-based, pero la lógica de usar el método es la misma independientemente de cómo se implemente el lado servidor del complemento.

• Tutorial de Excel: completado
• Escenario de tiempo de ejecución compartido de Excel
• Complemento de Office Microsoft Graph ASPNET
• Complemento de Office de Microsoft Graph React
• Complemento de Office SSO de NodeJS
• Inicio de sesión único de ASPNET del complemento de Office
• Ejemplo de monetización de SAAS del complemento de Office
• Complemento de Outlook ASPNET de Microsoft Graph
• Inicio de sesión único del complemento de Outlook
• Visor de tokens de complemento de Outlook
• Mensaje accionable del complemento de Outlook
• Uso compartido de complementos de Outlook en OneDrive
• Diagrama de inserción de ASPNET de Microsoft Graph del complemento de PowerPoint

Vea también

• Conjuntos de requisitos de la API de cuadros de diálogo
• Mejores prácticas y reglas para la API de diálogo de Office
• Autenticación con la API de cuadro de diálogo de Office
• Usar el cuadro de diálogo de Office para mostrar un vídeo
• Manejo de errores y eventos en el cuadro de diálogo de Office
• Tiempos de ejecución en complementos de Office