Behandeln von Fehlern und Ereignissen im Office-Dialogfeld
In diesem Artikel wird beschrieben, wie Fehler beim Öffnen des Dialogfelds und Fehler, die innerhalb des Dialogfelds 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-Dialog-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
displayDialogAsynczurü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 an displayDialogAsync übergebenen URL 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:
|
| 12003 | Das Dialogfeld wurde mit dem HTTP-Protokoll an eine URL weitergeleitet. HTTPS ist erforderlich. |
| 12006 | Eine der folgenden Varianten:
|
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.
Office Add-ins