Office.Dialog interface

Pacote:
office

O objeto que é retornado quando UI.displayDialogAsync é chamado. Ele expõe métodos para registrar manipuladores de eventos e fechar a caixa de diálogo.

Comentários

Conjunto de requisitos: DialogApi

Usada por

Exemplos

// 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 um manipulador de eventos. Os dois eventos com suporte são:

  • DialogMessageReceived. Disparado quando a caixa de diálogo envia uma mensagem para seu pai.

  • DialogEventReceived. Disparado quando a caixa de diálogo tiver sido fechada ou descarregada de outra forma.
close()

Chamado de uma página pai para fechar a caixa de diálogo correspondente.

Esse método é assíncrono. Ele não usa um parâmetro de retorno de chamada e não retorna um objeto Promise, portanto, não pode ser aguardado com a await palavra-chave ou a then função. Veja esta prática recomendada para obter mais informações: Abrir outra caixa de diálogo imediatamente após fechar uma
messageChild(message, messageOptions)

Entrega uma mensagem da página do host, como um painel de tarefas ou um arquivo de função sem interface do usuário, para uma caixa de diálogo que foi aberta na página.
sendMessage(name)

SOMENTE PARA USO INTERNO. NÃO CHAME SEU CÓDIGO.

Detalhes do método

addEventHandler(eventType, handler)

Registra um manipulador de eventos. Os dois eventos com suporte são:

  • DialogMessageReceived. Disparado quando a caixa de diálogo envia uma mensagem para seu pai.

  • DialogEventReceived. Disparado quando a caixa de diálogo tiver sido fechada ou descarregada de outra forma.

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

Parâmetros

eventType
Office.EventType

Deve ser DialogMessageReceived ou DialogEventReceived.

handler

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

Uma função que aceita um objeto com uma message propriedade andorigin, se eventType forDialogMessageReceived , ou um objeto com uma error propriedade, se eventType for DialogEventReceived. Observe que a origin propriedade está undefined em clientes que não dão suporte ao DialogOrigin 1.1.

Retornos

void

Exemplos

// 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()

Chamado de uma página pai para fechar a caixa de diálogo correspondente.

Esse método é assíncrono. Ele não usa um parâmetro de retorno de chamada e não retorna um objeto Promise, portanto, não pode ser aguardado com a await palavra-chave ou a then função. Veja esta prática recomendada para obter mais informações: Abrir outra caixa de diálogo imediatamente após fechar uma

close(): void;

Retornos

void

Exemplos

// 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 uma mensagem da página do host, como um painel de tarefas ou um arquivo de função sem interface do usuário, para uma caixa de diálogo que foi aberta na página.

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

Parâmetros

message

string

Aceita uma mensagem da página host para entregar à caixa de diálogo. Qualquer coisa que possa ser serializada em uma cadeia de caracteres, incluindo JSON e XML, pode ser enviada.

messageOptions
Office.DialogMessageOptions

Opcional. Fornece opções de como enviar a mensagem.

Retornos

void

Comentários

Aplicativos: Excel, Outlook (Requisito mínimo definido: Caixa de correio 1.9), PowerPoint, Word

Conjuntos de requisitos:

Embora o Outlook clássico no Mac não seja compatível com a Caixa de Correio 1.9, ele é compatível com a DialogApi 1.2.

Exemplos

// 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)

SOMENTE PARA USO INTERNO. NÃO CHAME SEU CÓDIGO.

sendMessage(name: string): void;

Parâmetros

name

string

Retornos

void