Office.UI interface

Agrega un controlador de eventos al objeto mediante el tipo de evento especificado.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

Devoluciones

Comentarios

Conjunto de requisitos: DialogAPI 1.2

Puede agregar varios controladores de eventos para el tipo de evento especificado siempre y cuando el nombre de cada función de controlador de eventos sea único.

Agrega un controlador de eventos al objeto mediante el tipo de evento especificado.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Parámetros

Devoluciones

Comentarios

Conjunto de requisitos: DialogAPI 1.2

Puede agregar varios controladores de eventos para el tipo de evento especificado siempre y cuando el nombre de cada función de controlador de eventos sea único.

Ejemplos

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

Cierra el contenedor de la interfaz de usuario donde se ejecuta JavaScript.

closeContainer(): void;

Devoluciones

Comentarios

Aplicaciones: Excel, Outlook (conjunto de requisitos mínimos: Buzón 1.5), PowerPoint, Word

Conjuntos de requisitos:

• DialogAPI

• Mailbox 1.5

El comportamiento de este método se especifica mediante lo siguiente:

• Se llama desde un botón de comando sin interfaz de usuario: sin efecto. No permanecerá abierto ningún cuadro de diálogo que se haya abierto mediante displayDialogAsync.

• Llamada desde un panel de tareas: se cerrará el panel de tareas. Cualquier cuadro de diálogo abierto por displayDialogAsync también se cerrará. Si el panel de tareas admite el anclaje y el usuario lo ancló, se desanclará.

• Se llama desde una extensión de módulo: sin efecto.

Ejemplos

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

Parámetros

Devoluciones

Comentarios

Aplicaciones: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

• DialogAPI

• Mailbox 1.4

Este método está disponible en el conjunto de requisitos DialogApi para complementos de Excel, PowerPoint o Word y en el conjunto de requisitos de buzón 1.4 para Outlook. Para obtener más información sobre cómo especificar un conjunto de requisitos en el manifiesto, vea Especificar aplicaciones de Office y requisitos de API, si usa el manifiesto de solo complemento. Si usa el manifiesto unificado para Microsoft 365, consulte Complementos de Office con el manifiesto de aplicación unificada para Microsoft 365.

La página inicial debe estar en el mismo dominio que la página primaria (el parámetro startAddress). Después de cargar la página inicial, puede ir a otros dominios.

Cualquier llamada a Office.context.ui.messageParent página también debe estar en el mismo dominio que la página primaria.

Consideraciones de diseño:

Las siguientes consideraciones de diseño se aplican a los cuadros de diálogo.

• Un panel de tareas de complemento de Office solo puede tener un cuadro de diálogo abierto en cualquier momento. Se pueden abrir varios diálogos al mismo tiempo desde Comandos de complemento (botones de cinta personalizados o elementos de menú).

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

• Cada cuadro de diálogo se centra en la pantalla cuando se abre.

• Los cuadros de diálogo aparecen sobre la aplicación y en el orden en que se crearon.

Use un cuadro de diálogo para:

• Mostrar páginas de autenticación para recopilar las credenciales de usuario.

• Muestra una pantalla de error, progreso o entrada desde un comando ShowTaskpane o ExecuteAction.

• Aumentar temporalmente el área de superficie que un usuario tiene disponible para completar una tarea.

No use un cuadro de diálogo para interactuar con un documento. En su lugar, use un panel de tareas.

Errores de displayDialogAsync

En la función de devolución de llamada que se pasa al método displayDialogAsync, puede usar las propiedades del objeto AsyncResult para devolver la siguiente información.

Ejemplos

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

Muestra un cuadro de diálogo para mostrar o recopilar información del usuario o para facilitar la navegación web.

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

Parámetros

Devoluciones

Comentarios

Aplicaciones: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

• DialogAPI

• Mailbox 1.4

Este método está disponible en el conjunto de requisitos DialogApi para complementos de Excel, PowerPoint o Word y en el conjunto de requisitos de buzón 1.4 para Outlook. Para obtener más información sobre cómo especificar un conjunto de requisitos en el manifiesto, vea Especificar aplicaciones de Office y requisitos de API, si usa el manifiesto de solo complemento. Si usa el manifiesto unificado para Microsoft 365, consulte Complementos de Office con el manifiesto de aplicación unificada para Microsoft 365.

La página inicial debe estar en el mismo dominio que la página primaria (el parámetro startAddress). Después de cargar la página inicial, puede ir a otros dominios.

Cualquier llamada a Office.context.ui.messageParent página también debe estar en el mismo dominio que la página primaria.

Consideraciones de diseño:

Las siguientes consideraciones de diseño se aplican a los cuadros de diálogo.

• Un panel de tareas de complemento de Office solo puede tener un cuadro de diálogo abierto en cualquier momento. Se pueden abrir varios diálogos al mismo tiempo desde Comandos de complemento (botones de cinta personalizados o elementos de menú).

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

• Cada cuadro de diálogo se centra en la pantalla cuando se abre.

• Los cuadros de diálogo aparecen sobre la aplicación y en el orden en que se crearon.

Use un cuadro de diálogo para:

• Mostrar páginas de autenticación para recopilar las credenciales de usuario.

• Muestra una pantalla de error, progreso o entrada desde un comando ShowTaskpane o ExecuteAction.

• Aumentar temporalmente el área de superficie que un usuario tiene disponible para completar una tarea.

No use un cuadro de diálogo para interactuar con un documento. En su lugar, use un panel de tareas.

Errores de displayDialogAsync

En la función de devolución de llamada que se pasa al método displayDialogAsync, puede usar las propiedades del objeto AsyncResult para devolver la siguiente información.

Entrega un mensaje desde el cuadro de diálogo a su pagina primaria o de apertura.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Parámetros

Devoluciones

Comentarios

Aplicaciones: Excel, Outlook, PowerPoint, Word

Conjuntos de requisitos:

• DialogAPI

• Mailbox 1.4

• Si se usa el messageOptions parámetro , también se requiere DialogOrigin 1.1 .

Ejemplos

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

Abre una ventana del explorador y carga la dirección URL especificada.

openBrowserWindow(url: string): void;

Parámetros

Devoluciones

Comentarios

Conjunto de requisitos: OpenBrowserWindowAPI 1.1

Ejemplos

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();