Share via

Controlar errores y eventos en el cuadro de diálogo de Office

  • Artículo

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 displayDialogAsync porque 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:
  • No existe ninguna página en la dirección URL que se pasó a displayDialogAsync.
  • Página que se pasó a displayDialogAsync cargada, pero el cuadro de diálogo se redirigió a una página que no encuentra ni carga, o bien se ha dirigido a una dirección URL con sintaxis no válida.
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:
  • El cuadro de diálogo se cerró, normalmente porque el usuario eligió el botón CerrarX.
  • El cuadro de diálogo devolvió un encabezado de respuesta Cross-Origin-Opener-Policy: same-origin . Para evitarlo, debe establecer el encabezado Cross-Origin-Opener-Policy: unsafe-none en o configurar el complemento y el cuadro de diálogo para que estén en el mismo dominio que la página host.

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.