Office.Dialog interface

Paket:
office

Das Objekt, das zurückgegeben wird, wenn UI.displayDialogAsync es aufgerufen wird. Es macht Methoden zum Registrieren von Ereignishandlern und zum Schließen des Dialogfelds verfügbar.

Hinweise

Anforderungssatz: DialogApi

Verwendet von

Beispiele

// 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.
        });
    }
);

Methoden

addEventHandler(eventType, handler)

Registriert einen Ereignishandler. Die beiden unterstützten Ereignisse sind:

  • DialogMessageReceived. Wird ausgelöst, wenn das Dialogfeld eine Nachricht an das übergeordnete Element sendet.

  • DialogEventReceived. Wird ausgelöst, wenn das Dialogfeld geschlossen oder anderweitig entladen wurde.
close()

Wird von einer übergeordneten Seite aufgerufen, um das entsprechende Dialogfeld zu schließen.

Diese Methode ist asynchron. Es wird kein Rückrufparameter verwendet, und es wird kein Promise-Objekt zurückgegeben, sodass weder mit dem await Schlüsselwort (Keyword) noch mit der then Funktion auf ihn gewartet werden kann. Weitere Informationen finden Sie in dieser bewährten Methode: Öffnen eines weiteren Dialogfelds unmittelbar nach dem Schließen eines Dialogfelds
messageChild(message, messageOptions)

Übermittelt eine Nachricht von der Hostseite, z. B. einen Aufgabenbereich oder eine Funktionsdatei ohne Benutzeroberfläche, an ein Dialogfeld, das auf der Seite geöffnet wurde.
sendMessage(name)

NUR FÜR DEN INTERNEN GEBRAUCH. RUFEN SIE IHREN CODE NICHT AUF.

Details zur Methode

addEventHandler(eventType, handler)

Registriert einen Ereignishandler. Die beiden unterstützten Ereignisse sind:

  • DialogMessageReceived. Wird ausgelöst, wenn das Dialogfeld eine Nachricht an das übergeordnete Element sendet.

  • DialogEventReceived. Wird ausgelöst, wenn das Dialogfeld geschlossen oder anderweitig entladen wurde.

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

Parameter

eventType
Office.EventType

Muss entweder DialogMessageReceived oder DialogEventReceived sein.

handler

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

Eine Funktion, die entweder ein Objekt mit einer messageorigin und-Eigenschaft, wenn eventType istDialogMessageReceived, oder ein Objekt mit einer error Eigenschaft, wenn eventType istDialogEventReceived, akzeptiert. Beachten Sie, dass sich die origin Eigenschaft auf Clients befindet undefined , die DialogOrigin 1.1 nicht unterstützen.

Gibt zurück

void

Beispiele

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

Wird von einer übergeordneten Seite aufgerufen, um das entsprechende Dialogfeld zu schließen.

Diese Methode ist asynchron. Es wird kein Rückrufparameter verwendet, und es wird kein Promise-Objekt zurückgegeben, sodass weder mit dem await Schlüsselwort (Keyword) noch mit der then Funktion auf ihn gewartet werden kann. Weitere Informationen finden Sie in dieser bewährten Methode: Öffnen eines weiteren Dialogfelds unmittelbar nach dem Schließen eines Dialogfelds

close(): void;

Gibt zurück

void

Beispiele

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

Übermittelt eine Nachricht von der Hostseite, z. B. einen Aufgabenbereich oder eine Funktionsdatei ohne Benutzeroberfläche, an ein Dialogfeld, das auf der Seite geöffnet wurde.

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

Parameter

message

string

Akzeptiert eine Nachricht von der Hostseite, die an das Dialogfeld übermittelt werden soll. Alles, was zu einer Zeichenfolge serialisiert werden kann, einschließlich JSON und XML, kann gesendet werden.

messageOptions
Office.DialogMessageOptions

Optional. Enthält Optionen für die Art und Weise, wie die Nachricht gesendet wird.

Gibt zurück

void

Hinweise

Anwendungen: Excel, Outlook (Mindestanforderung: Postfach 1.9), PowerPoint, Word

Anforderungssätze:

Obwohl das klassische Outlook auf Mac Postfach 1.9 nicht unterstützt, unterstützt es DialogApi 1.2.

Beispiele

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

NUR FÜR DEN INTERNEN GEBRAUCH. RUFEN SIE IHREN CODE NICHT AUF.

sendMessage(name: string): void;

Parameter

name

string

Gibt zurück

void