Erstellen von Seitenleisten in modellgesteuerten Apps mithilfe einer Client-API

Entwickler können App-Seitenbereiche innerhalb einer modellgesteuerten App erstellen und verwalten, indem sie die Xrm.App.sidePanes-API verwenden, die die Sammlung von Seitenbereichen darstellt. Das Aufrufen der createPane-Methode fügt einen neuen Bereich hinzu, der die Navigation zu jedem modellgesteuerten App-Formular oder einer benutzerdefinierten Seite ermöglicht. Seiten, die im Seitenbereich angezeigt werden, müssen in die Mindestbreite von 300 Pixeln passen und je nach Bereichsbreite auf größere Breiten angepasst werden können.

Registerkarten werden im Seitenbereich in zwei Gruppen aufgeführt: nicht verschließbar und verschließbar. Innerhalb jeder Gruppe werden die Registerkarten in der Reihenfolge aufgelistet, in der sie erstellt wurden. Die obere Gruppe enthält die Bereiche, die ein Benutzer nicht schließen kann, und die untere Gruppe enthält vom Benutzer schließbare Bereiche. Die nicht verschließbare Gruppe wird beim Öffnen der App befüllt, während die verschließbare Gruppe aufgrund von Benutzeraktionen innerhalb der App hinzugefügt wird.

Sie können einen von der Plattform bereitgestellten Header mit dem Titel und der Schaltfläche „Schließen“ verwenden oder Sie können einen benutzerdefinierten Header verwenden.

Sie können dem Seitenbereich ein Badge hinzufügen, um dem Benutzer anzuzeigen, dass eine Änderung beachtet werden muss. Das Badge unterstützt drei Modi: einen einfachen Punkt, eine Zählung oder ein Bild. Standardmäßig wird das Badge gelöscht, wenn der Benutzer zum Bereich wechselt. Sie können steuern, wann das Badge gelöscht wird.

App-Seitenbereiche werden nur in Webbrowsern unterstützt und in nativen Playern nicht zugelassen.

Anmerkung

Diese API ist nicht verfügbar für lokale Bereitstellungen von Dynamics 365 Customer Engagement. Weitere Informationen: Client APIs werden in Customer Engagement (on-premises) nicht unterstützt

In dieser Tabelle werden die Beispiele in diesem Artikel vorgestellt:

Example	Veranschaulicht
Anzeigen einer generativen Seite in einem Seitenbereich	Erstellen einer Seitenleiste und Navigieren zu einer generativen Seite anhand ihrer ID
Anzeigen einer Standardansicht im Seitenbereich	So zeigen Sie Standardtabellenansichten in nicht schließbaren Seitenbereichen an.
Tabellenzeile anzeigen	So zeigen Sie einen Datensatz in einem schließbaren Seitenbereich mit einer ausgeblendeten Kopfzeile und einer angegebenen Breite an.
Anzeigen einer Webressource	So zeigen Sie eine HTML-Webressource in einem nicht schließbaren Seitenbereich an.
Seitenbereiche verwalten	Einklappen, Erweitern, Ändern der Größe und Schließen von Bereiche und Festlegen eines Badges
Mit Xrm.App.panels.loadPanel verwenden	So verwenden Sie Seitenbereiche neben loadPanel und vermeiden Kompatibilitätseinschränkungen, indem Sie zu createPane wechseln.

Anzeigen einer generativen Seite in einem Seitenbereich

Verwenden Sie die navigate-Methode des Bereichs mit pageType: "generative" und der ID der generativen Seite:

const pane = await Xrm.App.sidePanes.createPane({
    title: "My Generative Page",
    paneId: "GenPage",
    canClose: true,
    width: 400
});

await pane.navigate({
    pageType: "generative",
    pageId: "<genPageID>"
});

Informationen zum Übergeben von Datensatzkontext und benutzerdefinierten Parametern finden Sie unter Navigieren zu und von einer generativen Seite.

Standardansicht im Seitenbereich anzeigen

Die folgenden Beispiele zeigen, wie die Standardansicht einer Tabelle im App-Seitenbereich angezeigt werden kann. Eine Reservierungsliste und Produktliste werden als nicht schließbare Bereiche geöffnet.

Xrm.App.sidePanes.createPane({
    title: "Reservations",
    imageSrc: "WebResources/sample_reservation_icon",
    paneId: "ReservationList",
    canClose: false
}).then((pane) => {
    pane.navigate({
        pageType: "entitylist",
        entityName: "sample_reservation",
    })
});

Xrm.App.sidePanes.createPane({
    title: "Products",
    imageSrc: "WebResources/sample_product_icon",
    paneId: "ProductList",
    canClose: false
}).then((pane) => {
    pane.navigate({
        pageType: "entitylist",
        entityName: "sample_product",
    })
});

Anzeigen einer Tabellenzeile

Dieses Beispiel zeigt, wie eine Zeile im Seitenbereich angezeigt wird. Die Reservierungszeile wird in einem Seitenbereich geöffnet, in dem die Standardüberschrift ausgeblendet ist und die Breite auf 600 Pixel festgelegt ist.

Xrm.App.sidePanes.createPane({
    title: "Reservation: Ammar Peterson",
    imageSrc: "WebResources/sample_reservation_icon",
    hideHeader: true,
    canClose: true,
    width: 600
}).then((pane) => {
    pane.navigate({
        pageType: "entityrecord",
        entityName: "sample_reservation",
        entityId: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    })
});

Anzeigen einer Webressource

In diesem Beispiel wird gezeigt, wie eine Webressource im Seitenbereich angezeigt wird. Eine benutzerdefinierte HTML-Seite wird in einem Seitenbereich geöffnet, in dem die Standardüberschrift sichtbar ist und die Schaltfläche "Schließen" ausgeblendet ist.

Xrm.App.sidePanes.createPane({
                        title: "Registration Page",
                        imageSrc: "WebResources/msfp_SurveyIcon_32",
                        paneId: "RegistrationPage",
                        canClose: false
                    }).then((pane) => {
                        //navigate to webresource
                        pane.navigate({
                            pageType: "webresource",
                            webresourceName: "new_RegistrationPage",
                        })
                    });

Seitenbereiche verwalten

Neben dem Erstellen von Seitenbereichen und dem Anzeigen von Zeilen oder Ansichten innerhalb des Seitenfensters können Sie auch:

• Verwenden Sie die state-Methode, um den Seitenbereich programmgesteuert auszublenden:

  Xrm.App.sidePanes.state = 0;

• Verwenden Sie die state-Methode, um den Seitenbereich programmgesteuert zu erweitern:

  Xrm.App.sidePanes.state = 1;

• Die Eigenschaften ändern, indem der ausgewählte Bereich abgerufen wird:

  var lastPane = Xrm.App.sidePanes.getSelectedPane();
lastPane.width = 400;

• Einen bestimmten Bereich mithilfe des paneId-Parameters abrufen:

  var reservationPane = Xrm.App.sidePanes.getPane("ReservationList");
reservationPane.close();

• Badge-Eigenschaft in einem Fensterbereich aktivieren:

  Xrm.App.sidePanes.getSelectedPane().badge = 1;

Verwendung mit Xrm.App.panels.loadPanel

Microsoft ersetzt die Xrm.Panels.loadPanel-API durch Xrm.App.sidePanes.createPane, da die erstere API nur einen einzelnen Bereich unterstützt, während die letztere API mehrere Bereiche unterstützt. Um den Übergang von loadPanel zu zu createPaneermöglichen, können die beiden APIs mit einigen Einschränkungen zusammenarbeiten. Wenn Sie nur loadPanel innerhalb einer modellgesteuerten App verwenden, bleibt die Benutzererfahrung gleich. Wenn Sie jedoch beides loadPanel verwenden und createPane, besteht die erste Einschränkung darin, dass für das loadPanelSymbol ein Platzhaltersymbol angezeigt wird. Die zweite Einschränkung besteht darin, dass die App, wenn der Benutzer vom loadPanel zum createPane wechselt, den loadPanel-Inhalt entlädt, um Arbeitsspeicher zu sparen, und ihn beim Zurückwechseln ohne den vorherigen Zustand wieder lädt. Diese Tab-Wechselfunktion ist das gleiche Verhalten, das im App-Modus für mehrere Sitzungen verwendet wird, um den von der App verwendeten Speicher zu verwalten. Die meisten Seitentypen werden ordnungsgemäß wiederhergestellt. Wenn jedoch eine externe Website oder Webressource geöffnet wird, wird der Zustand nicht wiederhergestellt.

Durch den Wechsel zur Verwendung von createPane können Sie beide Einschränkungen vermeiden, indem Sie ein Symbol bereitstellen und alwaysRender aktivieren. alwaysRender behält den Bereichsinhalt bei, wenn der Benutzer wechselt, nimmt jedoch mehr Speicher in Anspruch und sollte daher sparsam verwendet werden.

Ähnliche Artikel

sidePanes (Client-API-Referenz)
loadPanel (Client-API-Referenz)
Anleitung: Schreiben Sie Ihr erstes Clientskript