Trabajar con diálogos
En esta unidad, aprenderá a incorporar diálogos en libros de Excel. Aprenderá a abrir diálogos y a enviar y recuperar entradas y salidas para el diálogo.
Diálogos
La API de cuadro de diálogo es una extensión de la experiencia de usuario que los desarrolladores pueden personalizar en Office. Los desarrolladores pueden usarla para abrir diálogos desde complementos personalizados que interactúan con el usuario y la experiencia del usuario del complemento personalizado.
El escenario principal de la API de diálogo es la autenticación con proveedores de terceros. La mayoría de los proveedores de identidades impiden que sus experiencias de inicio de sesión se muestren en debido <iframe> a problemas relacionados con la toma de clics. Esto resulta problemático con un complemento, ya que se muestran en en <iframe>en algunos de los clientes, como las versiones web de las aplicaciones cliente de Office.
Otro desafío de los escenarios de autenticación es predecir los dominios que tendrán que cargarse. En escenarios de inicio de sesión federados, la posible lista de dominios podría ser infinita, lo que de nuevo resulta problemático en un complemento en el que todos los dominios deben registrarse en el manifiesto.
Es importante tener en cuenta que Office ofrece una experiencia de inicio de sesión único específica para las identidades de Microsoft. Si el complemento requiere datos sobre el usuario de Office o que sus recursos sean accesibles a través de Microsoft Graph, como, por ejemplo, Microsoft 365 o OneDrive, Microsoft recomienda usar la API de inicio de sesión único siempre que se pueda. Si usa las API en el inicio de sesión único, no necesitará la API de cuadros de diálogo.
Más allá de la autenticación, la API de cuadros de diálogo puede proporcionar más espacio de pantalla para los elementos difíciles de mostrar en un panel de tareas tradicional del complemento de contenido. Un buen ejemplo sería hospedar un vídeo que sería demasiado pequeño si se limitase a un panel de tareas
La API de cuadros de diálogo puede mostrar cualquier página web HTTPS, pero debe iniciarse primero en un dominio de aplicación y, después, redirigir.
Abrir diálogos
Abra un cuadro de diálogo con el método displayDialogAsync() desde un complemento de Office:
Office.context.ui.displayDialogAsync("<URL />", options, optionalCallback);
El método displayDialogAsync() acepta tres parámetros:
La
<URL />es la página que se va a mostrar en el cuadro de diálogo. Inicialmente es una página hospedada desde un dominio de aplicación, tal como se define en el manifiesto. Sin embargo, la página puede redirigirse inmediatamente a otra página.El parámetro
optionspermite al desarrollador modificar el tamaño del cuadro de diálogo. De forma predeterminada, el cuadro de diálogo se mostrará como el 80 % del alto y ancho de la pantalla del dispositivo. Los valores de alto y ancho se expresan como porcentaje de la pantalla del dispositivo.Opcionalmente, los desarrolladores pueden establecer la propiedad
displayInIframeen las opciones. Si se establece entrue, el cuadro de diálogo se mostrará como un Iframe flotante en lugar de como una ventana independiente (en los clientes que lo admiten), lo que hará que se abra más rápido.El
optionalCallbackpermite que la página host del complemento responda a los mensajes y eventos del cuadro de diálogo.
Entrada y salida del cuadro de diálogo
La manera principal de pasar información a un cuadro de diálogo es a través del almacenamiento local del explorador (window.localStorage) o a través de parámetros de dirección URL en la dirección URL del cuadro de diálogo. En este ejemplo, la página host pasa un identificador de "123" al cuadro de diálogo a través de un parámetro de dirección URL.
/******* START Host page script *******/
// Open the dialog passing the parameter id=123
let dialog = null;
Office.context.ui.displayDialogAsync(
'https://domain/popup.html?id=123',
{
height: 45,
width: 55
},
function(result) {
dialog = result.value;
// Listen for messages coming from the dialog
dialog.addEventHandler(
Microsoft.Office.WebExtension.EventType.DialogMessageReceived,
processMessage
);
}
);
function processMessage(arg) {
// Log the message send from the dialog and close the dialog
console.log(arg.message);
dialog.close();
}
/******* End Host page script *******/
/******* Start Dialog page script *******/
// dialog must call Office.initialize
Office.initialize = function() {
// send the parent/host a message
Office.context.ui.messageParent('Hello from the dialog!!!');
}
Un cuadro de diálogo puede devolver mensajes al host llamando a Office.context.ui.messageParent para enviar un valor booleano o un mensaje de cadena a la página host. En la parte inferior del ejemplo, puede ver el script de diálogo donde se pasa el mensaje "Hello del cuadro de diálogo!!" al elemento primario.
Solo se puede llamar al método messageParent() en una página con el mismo dominio (incluido el protocolo y el puerto) que la página host.
La página host debe escuchar los mensajes suscribiéndose al controlador de DialogMessageReceived. En el ejemplo, la página host registra este controlador mediante la función processMessage(), donde registra el mensaje en la consola.
Resumen
En esta unidad, ha aprendido a incorporar diálogos en libros de Excel. También ha aprendido a abrir diálogos y a enviar y recuperar entradas y salidas para el diálogo.