Share via

Mejores prácticas y reglas para la API de diálogo de Office

  • Artículo

En este artículo se proporcionan reglas, procedimientos recomendados y procedimientos recomendados para la API de diálogo de Office, 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).

Nota:

Para familiarizarse con los conceptos básicos del uso de la API de cuadro de diálogo de Office, consulte Uso de la API de diálogo de Office en los complementos de Office.

Vea también Control de errores y eventos con el cuadro de diálogo De Office.

Reglas y trucos

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

Intentar mostrar un cuadro de diálogo mientras se usa Office en la Web puede hacer que el bloqueador emergente del explorador bloquee el cuadro de diálogo. Para evitarlo, Office en la Web pide al usuario que permita o ignore la apertura del cuadro de diálogo.

Símbolo del sistema con una breve descripción y botones Permitir e Ignorar que un complemento puede generar para evitar bloqueos emergentes en el explorador.

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 12009, consulta Errores de displayDialogAsync).

Si, por cualquier motivo, quiere desactivar esta característica, el código debe rechazarse. Realiza esta solicitud con el objeto DialogOptions que se pasa al displayDialogAsync método . En concreto, el objeto debe incluir promptBeforeOpen: false. Cuando esta opción se establece en false, Office en la Web no pedirá al usuario que permita que el complemento abra un cuadro de diálogo y el cuadro de diálogo de Office no se abrirá.

Solicitar acceso a las funcionalidades del dispositivo en Office en la Web y nueva Outlook en Windows (versión preliminar)

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

Cuando el complemento llama a Office.context.devicePermission.requestPermissions o Office.context.devicePermission.requestPermissionsAsync, se muestra 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.

Nota:

  • Los complementos que se ejecutan en clientes de escritorio de Office o en exploradores que no se basan en Chromium muestran automáticamente un cuadro de diálogo que solicita el permiso de un usuario. El desarrollador no necesita implementar la API de permisos de dispositivo en estas plataformas.
  • Los complementos que se ejecutan en Safari no pueden acceder a las funcionalidades de dispositivo de un usuario. La API de permisos de dispositivo no se admite en Safari.

No use el valor _host_info

Office agrega automáticamente un parámetro de consulta llamado _host_info a la dirección URL que se pasa a displayDialogAsync. Se anexa después de los parámetros de consulta personalizados, si los hay. No se anexa a las direcciones URL posteriores a las que navega el cuadro de diálogo. Microsoft puede 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 , es posible que el primer cuadro de closediálogo no se haya cerrado por completo cuando Office intenta abrir el segundo. Si esto sucede, Office devolverá 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, sugerimos la siguiente técnica cuando necesite abrir un nuevo cuadro de diálogo 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 de forma recursiva si la llamada de displayDialogAsync devuelve 12007. A continuación se muestra un ejemplo.

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 . A continuación se muestra un ejemplo.

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 cuadro de diálogo de Office en una SPA

Si el complemento usa el enrutamiento del lado cliente, como suelen hacer las aplicaciones de página única (SPA), tiene la opción de 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. Se recomienda no hacerlo por los motivos que se indican a continuación.

Nota:

Este artículo no es relevante para el enrutamiento del lado servidor , como en una aplicación web basada en Express.

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 box, 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 pasara una ruta al displayDialogAsync método, no tendría realmente un SPA; tendría dos instancias del mismo SPA. Además, gran parte del código de la instancia del panel de tareas nunca se usaría en esa instancia y gran parte del código de la instancia del cuadro de diálogo nunca se usaría en esa instancia. Es como tener dos SPAs en el mismo paquete.

Recomendaciones de Microsoft

En lugar de pasar una ruta del lado cliente al displayDialogAsync método , se recomienda realizar una de las siguientes acciones:

  • 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 simplificará 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 esto significa que se está desviando de la idea literal de una aplicación de página única; realmente no tiene una sola instancia de un SPA cuando se usa la API de diálogo de Office.