Freigeben über

Client-API-Formularkontext

  • Artikel

Der Client-API-Formularkontext (formContext) bietet eine Referenz im Formular oder auf ein Element im Formular, wie z. B. ein Steuerelement für die Schnellansicht oder eine Zeile in einem bearbeitbaren Raster, für den der aktuelle Code ausgeführt wird.

Früher wurde das globale Xrm.Page-Objekt dazu verwendet, um ein Formular oder ein Element im Formular darzustellen. Mit der neuesten Version ist das Xrm.Page-Object veraltet, und Sie sollen nun die getFormContext-Methode aus dem zur Ausführung übergebenen Kontextobjekt verwenden, um die Referenz ins entsprechende Formular oder ein Element im Formular zurückzugeben.

Wichtig

Veraltet bedeutet, dass wir eine Funktion aus einer zukünftigen Version von modellgesteuerten Apps entfernen möchten; die Funktionen oder die Funktionalität wird weiterhin funktionieren und vollständig unterstützt, bis sie offiziell entfernt wird. Mindestens sechs Monate vor dem Entfernen wird eine öffentliche Ankündigung hier in der Dokumentation, im offiziellen Blog und an vielen anderen Orten ausgegeben.

Verwendung von Xrm.Page als statischen Zugang zum primären Formularkontext ist weiterhin unterstützt, um die vorhandene Abwärtskompatibilität mit Skripten beizubehalten und wird nicht entfernt, sobald weitere Client API-Methoden im Bereich der Client API-Veraltung entfernt werden. Es wird empfohlen, das Sie das neue formContext-Objekt und nicht das Xrm.Page-Objekt in Ihrer Codezielgruppenadressierung Version 9.0 oder höher verwenden, sofern möglich. Ein weiterer Vorteil der Verwendung des formContext-Objekts ist, dass es Ihnen ermöglicht, gemeinsame Ereignishandler zu erstellen, die entweder über ein Formular oder in einem bearbeitbaren Raster verwendet werden, je nachdem wo sie aufgerufen werden. Weitere Informationen: getFormContext (Client-API-Referenz).

Das Ziel für formContext JavaScript-Funktionen für Menübandaktionen abzurufen, ist jedoch unterschiedlich vom Abrufen von Formularskripts. Weitere Informationen: Formular- und Rasterkontext in Menübandaktionen.

Anmerkung

Formularkontexte sind nur während des Ereignisses gültig, an dem sie übergeben werden. Es gelten die gleichen Einschränkungen wie bei Ausführungskontexten

Verwendung des formContext-Objekts anstelle des Xrm.Page-Objekts

Es ist einfach, den vorhandenen Code mit Xrm.Page zu konvertieren, um das neue formContext-Objekt zu verwenden. Betrachten Sie beispielsweise das folgende Skript, das das Xrm.Page-Objekt verwendet:

function displayName()
{
   var firstName = Xrm.Page.getAttribute("firstname").getValue();
   var lastName = Xrm.Page.getAttribute("lastname").getValue();
   console.log(firstName + " " + lastName);
}

Hier finden Sie das aktualisierte Skript, das den zur Ausführung übergebenen Kontext verwendet, um das formContext-Objekt anstatt Verwendung des Xrm.Page-Objekts abzurufen:

function displayName(executionContext)
{
   var formContext = executionContext.getFormContext(); // get formContext

   // use formContext instead of Xrm.Page   
   var firstName = formContext.getAttribute("firstname").getValue(); 
   var lastName = formContext.getAttribute("lastname").getValue();
   console.log(firstName + " " + lastName);
}

Wichtig

Sie müssen daran denken, die Option Ausführungskontext als ersten Parameter übergeben im Dialogfeld Handlereigenschaften auszuwählen, während Sie die Ereignishandler für die Verwendung des Objekts formContext definieren. Weitere Informationen: Client-API-Ausführungskontext

formContext-Objektmodell

Verwenden Sie die Daten- und Benutzerschnittstelle-Objekte unter dem formContext-Objekt, um Daten oder Benutzerschnittstellenelemente in modellgesteuerten Apps programmgesteuert zu bearbeiten.

formContext-Objektmodell.

Datenobjekt

Stellt Eigenschaften und Methoden zur Verfügung, um mit den Daten auf einem Formular zu arbeiten, einschließlich Tabellendaten und Daten im Steuerelement für den Business Process Flow. Enthält die folgenden Objekte:

Object Beschreibung
attributes Sammlung von Nicht-Tabellendaten im Formular. Die Elemente in dieser Auflistung sind vom gleichen Typ wie die Spaltenauflistung, jedoch keine Spalten der Formulartabelle.
Weitere Informationen: Sammlungen.
entity Bietet Eigenschaften und Methoden zum Abrufen von Informationen, die spezifisch für den auf der Seite angezeigten Datensatz sind, die Speichermethode und eine Sammlung aller im Formular enthaltenen Spalten. Spaltendaten sind auf Spalten beschränkt, die im Formular dargestellt werden.
Weitere Informationen: formContext.data.entity
process Stellt Objekte und Methoden zum Interagieren mit den Geschäftsprozessfluss-Daten in einem Formular bereit.
Weitere Informationen: formContext.data.process

Es bietet auch eine Attribute Sammlung für den Zugriff auf nicht tabellengebundenes Steuerelement. Weitere Informationen finden Sie im Abschnitt Sammlungen im formContext-Objektmodell in diesem Artikel unten.

Weitere Informationen: formContext.data

Benutzerschnittstellenobjekt

Bietet neben Sammlungen für verschiedene Unterkomponenten des Formulars oder Rasters die Methoden zum Abrufen von Informationen über die Benutzerschnittstelle. Enthält die folgenden Objekte:

Object Beschreibung
formSelector Bietet eine Elementsammlung, die Funktionen zum Abfragen der Formulare, die für den aktuellen Benutzer verfügbar sind, bereitstellt. Verwenden Sie die Navigationsmethode, um das aktuelle Formular zu schließen und ein anderes zu öffnen.
navigation Enthält keine Methoden. Bietet Zugriff auf die Navigationselemente über die Elementsammlung. Weitere Informationen über Sammlungen finden Sie im folgenden Abschnitt.
process Stellt Methoden zum Interagieren mit den Geschäftsprozessflusssteuerung in einem Formular bereit.

Weitere Informationen: formContext.ui

Sammlungen im formContext-Objektmodell

Die folgende Tabelle beschreibt die Sammlungen im Xrm-Objektmodell. Weitere Informationen über die für Sammlungen allgemein verfügbaren Methode finden Sie unter Sammlungen (Client-API-Referenz).

Sammlung Beschreibung
Attribute Zwei Objekte enthalten eine Spaltensammlung:

- formContext.data.attributes Sammlung bietet Zugriff auf nicht tabellengebundenen Spalten.

- formContext.data.entity.attributes Sammlung bietet Zugriff auf jede Tabellenspalte, die im Formular verfügbar ist. Es sind nur die dem Formular hinzugefügten Spalten verfügbar.
Steuerelemente Drei Objekte enthalten eine Sammlung von Steuerelementen:

- formContext.ui.controls: Bietet den Zugriff auf jedes Steuerelement, das im Formular vorhanden ist.

- formContext.data.entity.attribute.controls: Da eine Spalte möglicherweise mehr als ein Steuerelement im Formular enthält, bietet diese Sammlung Zugriff auf jedes dieser Steuerelemente. Diese Sammlung enthält nur ein Element, es sei denn, dem Formular werden mehrere Steuerelemente für die Spalte hinzugefügt.

- formContext.ui.tabs.sections.controls: Diese Sammlung enthält nur die Steuerelemente, die im Bereich gefunden sind.
formContext.data.process.stages und formContext.data.process.steps Stellt den Zugriff auf die Phasen- und Schrittsammlungen in einem Geschäftsprozessfluss bereit. Diese erlauben auch das Hinzufügen und Entfernen der Elementen der Sammlung.
formContext.ui.formselector.Elemente Wenn für eine Tabelle mehrere Formulare bereitgestellt werden, können Sie jedem Formular Sicherheitsrollen zuordnen. Wenn die Sicherheitsrollen, die einem Benutzer zugeordnet sind, es diesem ermöglichen, mehr als ein Formular anzuzeigen, bietet die formContext.ui.formSelector.items-Sammlung den Zugriff auf jede Formulardefinition, die diesem Benutzer verfügbar ist.
formContext.ui.navigation.items Die formContext.ui.navigation.items-Sammlung bietet den Zugriff auf die Navigationselemente, die mithilfe des Navigationsbereichs des Formular-Editors definiert werden. Benutzer navigieren dazu mithilfe der Befehlsleiste.
formContext.ui.quickForms Stellt Methoden des Zugriffs auf sämtliche Steuerelemente für die Schnellansicht und deren zugehörigen Steuerelemente für die Formulare bereit.
formContext.ui.tabs Sie können jedes Formular organisieren, indem Sie eine oder mehrere Registerkarten verwenden. Diese Sammlung bietet Zugriff auf jede dieser Registerkarten.
formContext.ui Tab. Abschnitte Sie können jede Registerkarte im Formular organisieren, indem Sie einen oder mehrere Abschnitte verwenden. Die sections-Sammlung der Registerkarten bietet Zugriff auf jeden dieser Abschnitte. Sie müssen die Registerkarte definieren, die den gewünschten Abschnitt enthält, oder jede Registerkarte durchlaufen, um den entsprechenden Abschnitt zu finden.

getFormContext-Methode
getGlobalContext-Methode
getAttribute-Methode
getControl-Methode
Ausführungskontextmethoden