Controlar errores y eventos en el cuadro de diálogo de Office
En este artículo se describe cómo interceptar y controlar los errores al abrir el cuadro de diálogo y los errores que se producen dentro del cuadro de diálogo.
Nota:
En este artículo se presupone que está familiarizado con los conceptos básicos del uso de la API de cuadro de diálogo de Office, tal como se describe en Uso de la API de diálogo de Office en los complementos de Office.
Consulte también Procedimientos recomendados y reglas para la API de diálogo de Office.
El código debe controlar dos categorías de eventos.
- Errores devueltos por la llamada de
displayDialogAsyncporque no se puede crear el cuadro de diálogo. - Errores y otros eventos en el cuadro de diálogo.
Errores de displayDialogAsync
Además de los errores generales de la plataforma y del sistema, cuatro errores son específicos de llamar a displayDialogAsync.
| Número de código | Significado |
|---|---|
| 12004 | El dominio de la dirección URL que se pasa a displayDialogAsync no es de confianza. El dominio debe estar en el mismo dominio que la página host (incluido el número de puerto y el protocolo). |
| 12005 | La dirección URL pasada a displayDialogAsync utiliza el protocolo HTTP. Se necesita HTTPS. (En algunas versiones de Office, el texto del mensaje de error devuelto con 12005 es el mismo devuelto para 12004). |
| 12007 | Ya hay un cuadro de diálogo abierto en la ventana host. Una ventana host, como un panel de tareas, solo puede tener abierto un cuadro de diálogo al mismo tiempo. |
| 12009 | El usuario ha decidido ignorar el cuadro de diálogo. Este error puede producirse en Office en la Web, donde los usuarios pueden optar por no permitir que un complemento presente un cuadro de diálogo. Para obtener más información, consulte Control de bloqueadores emergentes con Office en la Web. |
| 12011 | El complemento se ejecuta en Office en la Web y la configuración del explorador del usuario está bloqueando los elementos emergentes. Esto suele ocurrir cuando el explorador es Heredado de Edge y el dominio del complemento está en una zona de seguridad diferente del dominio que el cuadro de diálogo está intentando abrir. Otro escenario que desencadena este error es que el explorador es Safari y está configurado para bloquear todos los elementos emergentes. Considere la posibilidad de responder a este error con un mensaje al usuario para cambiar la configuración del explorador o usar otro explorador. |
Cuando displayDialogAsync se llama a , pasa un objeto AsyncResult a su función de devolución de llamada. Cuando la llamada se realiza correctamente, se abre el cuadro de diálogo y la value propiedad del AsyncResult objeto es un objeto Dialog . Para obtener un ejemplo de esto, vea Enviar información desde el cuadro de diálogo a la página host. Cuando se produce un error en la llamada a displayDialogAsync , no se crea el cuadro de diálogo, la status propiedad del AsyncResult objeto se establece en Office.AsyncResultStatus.Failedy se rellena la error propiedad del objeto. Siempre debe proporcionar una devolución de llamada que pruebe status y responda cuando se trata de un error. Para obtener un ejemplo que notifica el mensaje de error independientemente de su número de código, vea el código siguiente. (La showNotification función, no definida en este artículo, muestra o registra el error. Para obtener un ejemplo de cómo puede implementar esta función dentro del complemento, consulte Ejemplo de la API de cuadro de diálogo de complementos de Office).
let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
showNotification(asyncResult.error.code = ": " + asyncResult.error.message);
} else {
dialog = asyncResult.value;
dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
}
});
Errores y eventos en el cuadro de diálogo
Tres errores y eventos en el cuadro de diálogo generarán un DialogEventReceived evento en la página host. Para obtener un recordatorio de lo que es una página host, vea Abrir un cuadro de diálogo desde una página host.
| Número de código | Significado |
|---|---|
| 12002 | Uno de los siguientes:
|
| 12003 | El cuadro de diálogo se ha dirigido a una dirección URL con el protocolo HTTP. Se necesita HTTPS. |
| 12006 | Uno de los siguientes:
|
Su código puede asignar un controlador para el evento DialogEventReceived en la llamada a displayDialogAsync. A continuación puede ver un ejemplo simple.
let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (result) {
dialog = result.value;
dialog.addEventHandler(Office.EventType.DialogEventReceived, processDialogEvent);
}
);
Para obtener un ejemplo de un controlador para el DialogEventReceived evento que crea mensajes de error personalizados para cada código de error, vea el ejemplo siguiente.
function processDialogEvent(arg) {
switch (arg.error) {
case 12002:
showNotification("The dialog box has been directed to a page that it cannot find or load, or the URL syntax is invalid.");
break;
case 12003:
showNotification("The dialog box has been directed to a URL with the HTTP protocol. HTTPS is required."); break;
case 12006:
showNotification("Dialog closed.");
break;
default:
showNotification("Unknown error in dialog box.");
break;
}
}
Consulte también
Para obtener un complemento que controle los errores de esta manera, vea el ejemplo de la API de cuadros de diálogo del complemento de Office.