Procedimientos recomendados y reglas para la API de cuadro de diálogo de Office

En este artículo se proporcionan reglas, limitaciones y procedimientos recomendados para office Dialog API, 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 navegar a direcciones URL HTTPS, no a HTTP.

• La dirección URL que se pasa al método displayDialogAsync debe estar en el mismo dominio que el propio complemento. No puede ser un subdominio. Sin embargo, la página que se pasa a ella 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 diálogos al mismo tiempo desde botones de cinta 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, vea Especificar aplicaciones de Office y requisitos de API).

• Normalmente se llama a la función messageParent desde una página del 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 de la parte superior de la aplicación de Office.

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

• Aparece un cuadro de diálogo 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 del del complemento y aplica el encabezado de respuesta Cross-Origin-Opener-Policy: same-origin, el complemento no podrá acceder a los mensajes del cuadro de diálogo y los usuarios verán el error 12006. Para evitar este error, establezca el encabezado Cross-Origin-Opener-Policy: unsafe-none en o configure el complemento y el cuadro de diálogo para que estén en el mismo dominio.

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

Procedimientos recomendados

Evitar 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. Para obtener un ejemplo de un panel de tareas con pestañas, vea el ejemplo SalesTracker del complemento de Excel para JavaScript .

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

Para ver los procedimientos recomendados en el diseño de cuadros de diálogo, vea Cuadros de diálogo en complementos de Office.

Controlar bloqueadores emergentes con Office en la Web

Si intenta mostrar un cuadro de diálogo mientras usa Office en la Web, el bloqueador emergente del explorador podría bloquear el cuadro de diálogo. Para evitar este problema, Office en la Web pide al usuario que permita o ignore 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 Omitir, el símbolo del sistema 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 debe detectar este error y proporcionar una experiencia alternativa que no requiera un cuadro de diálogo, o bien mostrar un mensaje al usuario que le indique que el complemento requiere que permita el diálogo. Para obtener más información sobre el error 12009, vea Errores de displayDialogAsync.

Controlar diálogos bloqueados (error 12009)

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

• Muestra un mensaje descriptivo que explica 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.
      }
    }
  );
  

• Proporcione un flujo de trabajo alternativo siempre que sea posible. Si el complemento puede funcionar con funcionalidades reducidas cuando se bloquea el cuadro de diálogo, ofrezca esa alternativa al usuario.

Deshabilitación del símbolo del sistema

Si desea desactivar la solicitud de permitir o omitir, el código debe desactivarse. Realice esta solicitud mediante el objeto DialogOptions que se pasa al displayDialogAsync método . En concreto, incluya promptBeforeOpen: false en el objeto . Al establecer esta opción en false, Office en la Web no pide 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 emergente del explorador lo bloquearía.

Solicitud de acceso a las funcionalidades del dispositivo en Office en la Web y nueva Outlook en Windows

Si el complemento requiere acceso a las funcionalidades 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 ejecutan 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 solicitadas 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 las direcciones URL posteriores a las que navega 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 que llame displayDialogAsync a 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 close, es posible que el primer cuadro de diálogo no esté completamente cerrado cuando Office intente abrir el segundo. Si esto sucede, Office devuelve un error 12007 : "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 con la await palabra clave o con un then método. Por este motivo, use la siguiente técnica cuando necesite abrir un cuadro de diálogo nuevo inmediatamente después de cerrar un cuadro de diálogo: encapsula el código para abrir el nuevo cuadro de diálogo en una función y diseña la función para llamarse a sí misma de forma recursiva 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 que el código se detenga antes de que intente 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 cuadros de diálogo de Office 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 a la dirección URL de una página HTML independiente. No use este enfoque por los motivos que se indican en la sección siguiente.

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

El cuadro de diálogo de Office se encuentra en una nueva ventana con su propia instancia del motor de 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 la aplicación en la ventana del 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 ), que no es accesible desde el código del panel de tareas. El cuadro de diálogo y la página host en la que displayDialogAsync se llamó parecen dos clientes diferentes al servidor. (Para obtener un recordatorio de lo que es una página host, vea Abrir un cuadro de diálogo desde una página host).

Por lo tanto, si pasa una ruta al displayDialogAsync método, usted no tiene realmente un SPA; usted 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 lote.

Recomendaciones de Microsoft

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

• 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, tener 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 lógica simple en el cuadro de diálogo. En tales casos, el proyecto se simplifica considerablemente mediante el hospedaje de una sola página HTML, con JavaScript incrustado o al que se hace referencia, en el dominio de la 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, realmente no tiene una sola instancia de una SPA cuando se usa la API de diálogo de Office.

Vea también

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