Prácticas recomendadas y reglas para la API de diálogo de Office

En este artículo se proporcionan las reglas, limitaciones y procedimientos recomendados para la API de Office Dialog , incluidos los procedimientos recomendados para diseñar la interfaz de usuario de un cuadro de diálogo y usar la API dentro de una aplicación de página única (SPA).

Reglas y limitaciones

• Un cuadro de diálogo solo puede ir a direcciones URL HTTPS, no a HTTP.

• La dirección URL que pase al método displayDialogAsync debe estar exactamente en el mismo dominio que el propio complemento. No puede ser un subdominio. Sin embargo, la página que le pase puede redirigir a una página de otro dominio.

• Una página host solo puede tener un cuadro de diálogo abierto a la vez. La página host puede ser un panel de tareas o el archivo de función de un comando de función. Puede abrir varios cuadros de diálogo al mismo tiempo desde botones de cinta de opciones personalizados o elementos de menú.

• El cuadro de diálogo solo puede llamar a dos API de Office:

  • Office.context.ui.messageParent
  • Office.context.requirements.isSetSupported (Para obtener más información, consulte Especificación de aplicaciones de Office y requisitos de API).

• Normalmente, se llama a la función messageParent desde una página exactamente en el mismo dominio que el propio complemento, pero esto no es obligatorio. Para obtener más información, consulte Mensajería entre dominios al tiempo de ejecución del host.

• Cuando se abre un cuadro de diálogo, se centra en la pantalla sobre la aplicación de Office.

• El usuario puede mover y cambiar el tamaño de un cuadro de diálogo.

• Un cuadro de diálogo se muestra en el orden en que se crea.

  Sugerencia

  En Office en la Web y en el nuevo Outlook en Windows, si el dominio del cuadro de diálogo es diferente al del complemento y aplica el encabezado de respuesta Cross-Origin-Opener-Policy: mismo origen, el complemento tiene bloqueado el acceso a los mensajes del cuadro de diálogo y los usuarios ven el error 12006. Para evitar este error, establezca el encabezado Cross-Origin-Opener-Policy: unsafe-none o configure el complemento y el cuadro de diálogo para que estén en el mismo dominio.

• En Outlook en la Web y en el nuevo Outlook en Windows, no establezca la propiedad window.name al configurar un cuadro de diálogo en el complemento. Estos clientes de Outlook utilizan la propiedad para mantener la window.name funcionalidad en los redireccionamientos de página.

Procedimientos recomendados

Evite el uso excesivo de cuadros de diálogo

Debido a que no se recomienda la superposición de elementos de interfaz de usuario, evite abrir un cuadro de diálogo desde un panel de tareas, a menos que el escenario lo requiera. Si se plantea cómo usar el área de superficie de un panel de tareas, tenga en cuenta que los paneles de tareas pueden organizarse por pestañas.

Diseñar una interfaz de usuario de cuadro de diálogo

Para conocer las prácticas recomendadas en el diseño de cuadros de diálogo, vea Cuadros de diálogo en complementos de Office.

Controlar bloqueadores de elementos emergentes con Office en la Web

Si intenta mostrar un cuadro de diálogo mientras usa Office en la Web, es posible que el bloqueador de elementos emergentes del explorador bloquee el cuadro de diálogo. Para evitar este problema, Office en la Web solicita al usuario que permita u omita la apertura del cuadro de diálogo.

Si el usuario elige Permitir, se abre el cuadro de diálogo de Office. Si el usuario elige Ignorar, el mensaje se cierra y el cuadro de diálogo de Office no se abre. En su lugar, el método devuelve el displayDialogAsync error 12009. El código debería detectar este error y proporcionar una experiencia alternativa que no requiera un cuadro de diálogo o mostrar un mensaje al usuario informando de que el complemento requiere que permita el cuadro de diálogo. Para obtener más información sobre el error 12009, consulte Errores de displayDialogAsync.

Controlar diálogos bloqueados (error 12009)

El complemento siempre debe controlar el error 12009 correctamente. Estos son algunos enfoques recomendados:

• Mostrar un mensaje descriptivo que explique por qué se necesita el cuadro de diálogo.

  Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/auth.html",
    { height: 60, width: 30 },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        if (asyncResult.error.code === 12009) {
          // User blocked the dialog.
          showNotification(
            "Dialog Required",
            "This add-in needs to open a dialog to sign you in. " +
            "Please click the add-in button again and choose 'Allow' when prompted."
          );
        } else {
          // Handle other errors.
          showNotification("Error", `Unable to open dialog: ${asyncResult.error.message}`);
        }
      } else {
        // Dialog opened successfully.
        const dialog = asyncResult.value;
        // ... Handle dialog events here.
      }
    }
  );
  

• Proporciona un flujo de trabajo alternativo siempre que sea posible. Si el complemento puede funcionar con capacidades reducidas cuando el cuadro de diálogo está bloqueado, ofrezca esa alternativa al usuario.

Deshabilitar la solicitud

Si desea desactivar el mensaje de permitir o ignorar, el código debe optar por no participar. Realice esta solicitud utilizando el objeto DialogOptions que pasa al displayDialogAsync método. En concreto, incluir promptBeforeOpen: false en el objeto. Cuando establece esta opción en false, Office en la Web no solicita al usuario que permita que el complemento abra un cuadro de diálogo y el cuadro de diálogo de Office no se abre si el bloqueador de elementos emergentes del explorador lo bloquea.

Solicitar acceso a las funcionalidades del dispositivo en Office en la Web y en el nuevo Outlook en Windows

Si el complemento requiere acceso a las capacidades de dispositivo de un usuario, use la API de permisos de dispositivo para solicitar permisos a través de un cuadro de diálogo. Las funcionalidades del dispositivo incluyen la cámara, la geolocalización y el micrófono de un usuario. Este requisito se aplica a las siguientes aplicaciones de Office.

• Office en la Web (Excel, Outlook, PowerPoint y Word) que se ejecuta en exploradores basados en Chromium, como Microsoft Edge o Google Chrome
• nuevo Outlook en Windows

Cuando el complemento llama a Office.context.devicePermission.requestPermissions o Office.context.devicePermission.requestPermissionsAsync, aparece un cuadro de diálogo con las funcionalidades del dispositivo solicitado y las opciones Permitir, Permitir una vez o Denegar acceso. Para obtener más información, vea Ver, administrar e instalar complementos para Excel, PowerPoint y Word.

No use el valor _host_info

Office agrega automáticamente un parámetro de consulta denominado _host_info a la dirección URL que se pasa a displayDialogAsync. Anexa este parámetro después de los parámetros de consulta personalizados, si los hay. No anexa este parámetro a ninguna URL posterior a la que navegue el cuadro de diálogo. Microsoft podría cambiar el contenido de este valor o quitarlo por completo, por lo que el código no debería leerlo. El mismo valor se agrega al almacenamiento de sesión del cuadro de diálogo (es decir, la propiedad Window.sessionStorage ). De nuevo, el código no debe leer ni escribir en este valor.

Abrir otro cuadro de diálogo inmediatamente después de cerrar uno

No puede tener más de un cuadro de diálogo abierto desde una página host determinada, por lo que el código debe llamar a Dialog.close en un cuadro de diálogo abierto antes de llamar displayDialogAsync para abrir otro cuadro de diálogo. El close método es asincrónico. Por este motivo, si llama displayDialogAsync inmediatamente después de una llamada de , es posible que el primer cuadro de closediálogo no se cierre completamente cuando Office intente abrir el segundo. Si esto ocurre, Office devuelve un error 12007 : "Se ha producido un error en la operación porque este complemento ya tiene un cuadro de diálogo activo".

El close método no acepta un parámetro de devolución de llamada y no devuelve un objeto Promise, por lo que no se puede esperar ni con la await palabra clave ni con un then método. Por esta razón, use la siguiente técnica cuando necesite abrir un nuevo cuadro de diálogo inmediatamente después de cerrar un cuadro de diálogo: encapsule el código para abrir el nuevo cuadro de diálogo en una función y diseñe la función para que se llame recursivamente a sí misma si la llamada de displayDialogAsync devuelve 12007. En el ejemplo siguiente se muestra cómo implementar esta técnica.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/firstDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        openSecondDialog();
      }
      else {
         // Handle errors.
      }
    }
  );
}
 
function openSecondDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/secondDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        if (result.error.code === 12007) {
          openSecondDialog(); // Recursive call.
        }
        else {
         // Handle other errors.
        }
      }
    }
  );
}

Como alternativa, puede forzar la pausa del código antes de intentar abrir el segundo cuadro de diálogo mediante el método setTimeout . En el ejemplo siguiente se muestra cómo implementar este enfoque.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/firstDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        setTimeout(() => { 
          Office.context.ui.displayDialogAsync(
            "https://MyDomain/secondDialog.html",
            { width: 50, height: 50 },
            (result) => {
              // Callback body.
            }
          );
        }, 1000);
      }
      else {
         // Handle errors.
      }
    }
  );
}

Procedimientos recomendados para usar la API de Office Dialog en un SPA

Si el complemento usa el enrutamiento del lado cliente, como suelen hacer las aplicaciones de página única (SPA), puede pasar la dirección URL de una ruta al método displayDialogAsync en lugar de la dirección URL de una página HTML independiente. No use este enfoque por las razones expuestas en la sección siguiente.

Problemas con SPA y la API de diálogo de Office

El cuadro de diálogo de Office se encuentra en una ventana nueva con su propia instancia del motor JavaScript y, por tanto, su propio contexto de ejecución completo. Si pasa una ruta, la página base y todo su código de inicialización y arranque se ejecutan de nuevo en este nuevo contexto, y las variables se establecen en sus valores iniciales en el cuadro de diálogo. Por lo tanto, esta técnica descarga e inicia una segunda instancia de su aplicación en el cuadro de diálogo, lo que anula parcialmente el propósito de un SPA. Además, el código que cambia las variables en la ventana del cuadro de diálogo no cambia la versión del panel de tareas de las mismas variables. De forma similar, la ventana del cuadro de diálogo tiene su propio almacenamiento de sesión (la propiedad Window.sessionStorage ), al que no se puede acceder desde el código del panel de tareas. El cuadro de diálogo y la página de host en la que displayDialogAsync se ha llamado parecen dos clientes diferentes para su servidor. (Para recordar qué es una página host, consulte Abrir un cuadro de diálogo desde una página host).

Por lo tanto, si pasa una ruta al displayDialogAsync método, realmente no tiene un SPA; tiene dos instancias del mismo SPA. Además, gran parte del código de la instancia del panel de tareas nunca se usa en esa instancia y gran parte del código de la instancia del cuadro de diálogo nunca se usa en esa instancia. Es como tener dos SPA en el mismo paquete.

Recomendaciones de Microsoft

En lugar de pasar una ruta del lado cliente al displayDialogAsync método, utilice uno de los siguientes métodos.

• Si el código que desea ejecutar en el cuadro de diálogo es lo suficientemente complejo, cree dos SPA diferentes explícitamente; es decir, tienen dos SPA en carpetas diferentes del mismo dominio. Una SPA se ejecuta en el cuadro de diálogo y la otra en la página host del cuadro de diálogo donde displayDialogAsync se llamó.
• En la mayoría de los escenarios, solo se necesita una lógica simple en el cuadro de diálogo. En tales casos, su proyecto se simplifica enormemente al alojar una sola página HTML, con JavaScript incrustado o referenciado, en el dominio de su SPA. Pase la dirección URL de la página al método displayDialogAsync. Aunque este enfoque significa que se desvía de la idea literal de una aplicación de página única, en realidad no tiene una única instancia de una SPA cuando usa la API de Office Dialog.

Vea también

• Usar la API de diálogo de Office en complementos de Office
• Controlar errores y eventos en el cuadro de diálogo de Office