Office.Dialog interface

Paquete:
office

Objeto que se devuelve cuando UI.displayDialogAsync es llamado. Expone métodos para registrar controladores de eventos y cerrar el cuadro de diálogo.

Comentarios

Conjunto de requisitos: DialogApi

Usada por

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 and how to use that handler to close the dialog.

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();
            // Do something to process the message.
        });
    }
);

// 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();
            // Do something to process the message.
        });
    }
);

Métodos

addEventHandler(eventType, handler)

Registra un controlador de eventos. Los dos eventos compatibles son:

  • DialogMessageReceived. Se desencadena cuando el cuadro de diálogo envía un mensaje a su elemento principal.

  • DialogEventReceived. Se desencadena cuando el cuadro de diálogo se ha cerrado o descargado.
close()

Llamado desde una página principal para cerrar el cuadro de diálogo correspondiente.

Este método es asincrónico. No toma un parámetro de devolución de llamada y no devuelve un objeto Promise, por lo que no se puede esperar ni con la palabra clave ni con await la then función. Consulte este procedimiento recomendado para obtener más información: Abrir otro cuadro de diálogo inmediatamente después de cerrar uno
messageChild(message, messageOptions)

Entrega un mensaje desde la página host, como un panel de tareas o un archivo de función sin interfaz de usuario, a un cuadro de diálogo que se abrió desde la página.
sendMessage(name)

SOLO PARA USO INTERNO. NO LLAME AL CÓDIGO.

Detalles del método

addEventHandler(eventType, handler)

Registra un controlador de eventos. Los dos eventos compatibles son:

  • DialogMessageReceived. Se desencadena cuando el cuadro de diálogo envía un mensaje a su elemento principal.

  • DialogEventReceived. Se desencadena cuando el cuadro de diálogo se ha cerrado o descargado.

addEventHandler(eventType: Office.EventType, handler: (args: {message: string, origin: string | undefined} | {error: number}) => void): void;

Parámetros

eventType
Office.EventType

Debe ser DialogMessageReceived o DialogEventReceived.

handler

(args: {message: string, origin: string | undefined} | {error: number}) => void

Una función que acepta un objeto con una message propiedad yorigin, si eventType esDialogMessageReceived , o un objeto con una error propiedad, si eventType es DialogEventReceived. Tenga en cuenta que la origin propiedad está en clientes que no admiten undefinedDialogOrigin 1.1.

Devoluciones

void

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 and how to use that handler to close 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);
        });
    }
);

close()

Llamado desde una página principal para cerrar el cuadro de diálogo correspondiente.

Este método es asincrónico. No toma un parámetro de devolución de llamada y no devuelve un objeto Promise, por lo que no se puede esperar ni con la palabra clave ni con await la then función. Consulte este procedimiento recomendado para obtener más información: Abrir otro cuadro de diálogo inmediatamente después de cerrar uno

close(): void;

Devoluciones

void

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 and how to use that handler to close 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);
        });
    }
);

messageChild(message, messageOptions)

Entrega un mensaje desde la página host, como un panel de tareas o un archivo de función sin interfaz de usuario, a un cuadro de diálogo que se abrió desde la página.

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

Parámetros

message

string

Acepta un mensaje de la página host para entregarlo al cuadro de diálogo. Se puede enviar todo lo que se pueda serializar en una cadena, incluidos JSON y XML.

messageOptions
Office.DialogMessageOptions

Opcional. Proporciona opciones sobre cómo enviar el mensaje.

Devoluciones

void

Comentarios

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

Conjuntos de requisitos:

Aunque la versión clásica de Outlook para Mac no es compatible con Buzón 1.9, sí admite DialogApi 1.2.

Ejemplos

// The following example shows how to send information about the current active worksheet to the dialog.
await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

sendMessage(name)

SOLO PARA USO INTERNO. NO LLAME AL CÓDIGO.

sendMessage(name: string): void;

Parámetros

name

string

Devoluciones

void