Behandeln von Fehlern und Ereignissen im Office-Dialogfeld

In diesem Artikel wird beschrieben, wie Fehler beim Öffnen des Dialogfelds und Fehler, die im Dialogfeld auftreten, abgefangen und behandelt werden.

Hinweis

Dieser Artikel setzt voraus, dass Sie mit den Grundlagen der Verwendung der Office-Dialog-API vertraut sind, wie unter Verwenden der Office-Dialogfeld-API in Ihren Office-Add-Ins beschrieben.

Weitere Informationen finden Sie unter Bewährte Methoden und Regeln für die Office-Dialog-API.

Ihr Code sollte zwei Kategorien von Ereignissen behandeln.

• Fehler, die vom Aufruf von displayDialogAsync zurückgegeben werden, weil das Dialogfeld nicht erstellt werden kann.
• Fehler und andere Ereignisse im Dialogfeld.

Fehler von displayDialogAsync

Zusätzlich zu allgemeinen Plattform- und Systemfehlern sind vier Fehler spezifisch für den Aufruf displayDialogAsyncvon .

Codenummer	Bedeutung
12004	Die Domäne der URL, die an displayDialogAsync übergeben wurde, ist nicht vertrauenswürdig. Die Domäne muss identisch sein mit der Domäne der Hostseite (inklusive Protokoll und Portnummer).
12005	Die URL, die an displayDialogAsync übergeben wurde, verwendet das HTTP-Protokoll. HTTPS ist erforderlich. (In einigen Versionen von Office entspricht der mit 12005 zurückgegebene Fehlermeldungstext dem für 12004 zurückgegebenen Text.)
12007	Ein Dialogfeld ist bereits in diesem Hostfenster geöffnet. In einem Hostfenster, z. B. einem Aufgabenbereich, kann immer nur ein Dialogfeld geöffnet sein.
12009	Der Benutzer hat das Dialogfeld ignoriert. Dieser Fehler kann in Office im Web auftreten, bei dem Benutzer festlegen können, dass ein Add-In kein Dialogfeld angezeigt wird. Weitere Informationen finden Sie unter Behandeln von Popupblockern mit Office im Web.
12011	Das Add-In wird in Office im Web ausgeführt, und die Browserkonfiguration des Benutzers blockiert Popups. Dies geschieht am häufigsten, wenn der Browser die Edge-Legacyversion aufweist und sich die Domäne des Add-Ins in einer anderen Sicherheitszone befindet als die Domäne, die das Dialogfeld zu öffnen versucht. Ein weiteres Szenario, das diesen Fehler auslöst, ist, dass der Browser Safari ist und so konfiguriert ist, dass alle Popups blockiert werden. Erwägen Sie, auf diesen Fehler mit einer Aufforderung an den Benutzer zu reagieren, seine Browserkonfiguration zu ändern oder einen anderen Browser zu verwenden.

Wenn displayDialogAsync aufgerufen wird, übergibt es ein AsyncResult-Objekt an seine Rückruffunktion. Wenn der Aufruf erfolgreich ist, wird das Dialogfeld geöffnet, und die value -Eigenschaft des AsyncResult -Objekts ist ein Dialog-Objekt . Ein Beispiel hierfür finden Sie unter Senden von Informationen aus dem Dialogfeld an die Hostseite. Wenn der Aufruf von displayDialogAsync fehlschlägt, wird das Dialogfeld nicht erstellt, die status -Eigenschaft des AsyncResult -Objekts wird auf Office.AsyncResultStatus.Failedfestgelegt, und die error -Eigenschaft des -Objekts wird aufgefüllt. Sie sollten immer einen Rückruf bereitstellen, der testet status und antwortet, wenn es sich um einen Fehler handelt. Ein Beispiel, das die Fehlermeldung unabhängig von ihrer Codenummer meldet, finden Sie im folgenden Code. (Die showNotification Funktion, die in diesem Artikel nicht definiert ist, zeigt den Fehler entweder an oder protokolliert sie. Ein Beispiel dafür, wie Sie diese Funktion in Ihrem Add-In implementieren können, finden Sie unter Office-Add-In-Dialogfeld-API-Beispiel.)

let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        showNotification(asyncResult.error.code = ": " + asyncResult.error.message);
    } else {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
});

Fehler und Ereignisse im Dialogfeld

Drei Fehler und Ereignisse im Dialogfeld lösen ein DialogEventReceived Ereignis auf der Hostseite aus. Eine Erinnerung an eine Hostseite finden Sie unter Öffnen eines Dialogfelds von einer Hostseite aus.

Codenummer	Bedeutung
12002	Eine der folgenden Varianten: – An der URL, die andisplayDialogAsync übergeben wurde, ist keine Seite vorhanden. – Die Seite, die an displayDialogAsync geladen übergeben wurde, aber das Dialogfeld wurde dann zu einer Seite umgeleitet, die es nicht finden oder laden kann, oder es wurde an eine URL mit ungültiger Syntax weitergeleitet.
12003	Das Dialogfeld wurde mit dem HTTP-Protokoll an eine URL weitergeleitet. HTTPS ist erforderlich.
12006	Das Dialogfeld wurde geschlossen, in der Regel, weil der Benutzer die Schaltfläche SchließenX ausgewählt hat.

Der Code kann einen Handler für das DialogEventReceived-Ereignis im Aufruf von displayDialogAsync zuweisen. Nachfolgend sehen Sie ein einfaches Beispiel.

let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
    function (result) {
        dialog = result.value;
        dialog.addEventHandler(Office.EventType.DialogEventReceived, processDialogEvent);
    }
);

Ein Beispiel für einen Handler für das Ereignis, das DialogEventReceived benutzerdefinierte Fehlermeldungen für jeden Fehlercode erstellt, finden Sie im folgenden Beispiel.

function processDialogEvent(arg) {
    switch (arg.error) {
        case 12002:
            showNotification("The dialog box has been directed to a page that it cannot find or load, or the URL syntax is invalid.");
            break;
        case 12003:
            showNotification("The dialog box has been directed to a URL with the HTTP protocol. HTTPS is required.");            break;
        case 12006:
            showNotification("Dialog closed.");
            break;
        default:
            showNotification("Unknown error in dialog box.");
            break;
    }
}

Siehe auch

Ein Beispiel-Add-In, das Fehler auf diese Art und Weise behandelt, finden Sie unter Dialog-API-Beispiel für Office-Add-In.