Überschreiben Sie Speicher-, Aktualisierungs- und Ladeereignisse für bearbeitbare Felder im zugrunde liegenden Datensatzraster

Als Entwickler verwenden Sie diese Referenzdokumentation, um mehr über die Ereignisse und das Kontextobjekt der Planung zu erfahren.

Lizenz- und Rollenanforderungen

Anforderungstyp	Sie benötigen
Lizenz	Dynamics 365 Sales Premium oder Dynamics 365 Sales Enterprise Weitere Informationen: Dynamics 365 Sales-Preise.
Sicherheitsrollen	Systemanpasser Weitere Informationen: Vordefinierte Sicherheitsrollen für Vertrieb

Notiz

Das Prognose-Kontextobjekt, auf das in diesem Thema Bezug genommen wird, unterscheidet sich vom Ausführungskontext Microsoft Dataverse. Das Forecasting-Kontextobjekt ist spezifisch für die Planung und unterstützt die erweiterten Konfigurationen des zugrunde liegenden Rasters der Datensätze.

Ereignisse für das zugrunde liegende Raster der Datensätze

Die folgenden Ereignisse werden in der Planung unterstützt:

• OnRowLoad
• OnSave
• OnChange

Die folgenden Beispielszenarien werden auf der Grundlage der unterstützten Handler für Ereignisse erstellt:

• Ein Raster schreibgeschützt machen durch Deaktivieren aller Felder.
• Stets nur wenige Felder auf Basis der Entität aktivieren.
• Bearbeitung von Feldern basierend auf Logik und Entität deaktivieren.
• Anzeigen einer Fehlermeldung basierend auf dem Wert.
• Blockieren Sie die automatische Speicherung auf der Basis des geschätzten Wertes mit preventDefault und öffnen Sie ein Ereignis im Fenster.

OnRowLoad Ereignis

Das Ereignis OnRowLoad wird für jeden zugrunde liegenden Datensatz ausgelöst, der in das Raster geladen wird. Das Kontextobjekt, das an den Handler für das Ereignis OnRowLoad übergeben wird, enthält APIs, die für den zugrunde liegenden Datensatz spezifisch sind.

Im Folgenden finden Sie Beispiele für Szenarien, die Sie mit dem Handler OnRowLoad durchführen können:

• Ein Raster schreibgeschützt machen durch Deaktivieren aller Felder.
• Stets nur wenige Felder auf Basis der Entität aktivieren.
• Bearbeitung von Feldern basierend auf Logik und Entität deaktivieren.

Notiz

Für die Planung werden die zugrunde liegenden Datensätze der verschiedenen Entitäten durch Auswahl des Attributs Groupby im bearbeitbaren Raster der Planung angezeigt. Um die Logik auf der Grundlage dieser Entitäten zu handhaben, sehen Sie sich die Beispiele Immer nur einige Felder auf der Grundlage der Entität aktivieren und Die Bearbeitung von Feldern auf der Grundlage von Logik und Entität deaktivieren an.

OnChange-Ereignis

Das Ereignis OnChange wird ausgelöst, wenn der Wert einer Zelle im bearbeitbaren Raster der Planung aktualisiert wird und die Zelle nicht mehr im Fokus ist.

Notiz

• Für das bearbeitbare Raster der Planung löst jede Feldänderung die Ereignis-Handler OnChange und OnSave aus, sofern sie vorhanden sind.
• Das Speichern wird nicht ausgelöst, wenn ein Feld mit einer Fehlermeldung über die Client API im OnChange-Handler festgelegt wird. Für Benachrichtigungen im Zusammenhang mit Client-APIs für die Planung gehen Sie zur API setNotification in context.getFormContext().data.entity.attributes.getByName("Attribut Name").controls.get(0).
• Es gibt keine Zuordnung zwischen Attributen und dem Handler OnChange, und jede Feldänderung löst den Handler OnChange mit dem Kontextobjektparameter aus. Um das Attribut zu identifizieren, das den Handler ausgelöst hat, verwenden Sie die Funktion getIsDirty für das Attributobjekt. Weitere Informationen: context.getFormContext().data.entity.attributes.getByName("Attribut Name")

Im Folgenden sehen Sie ein Beispielszenario, das Sie mit dem Handler OnChange ausführen können:

• Fehlerbenachrichtigung basierend auf dem Wert anzeigen.

OnSave Ereignis

Das Ereignis OnSave wird ausgelöst, wenn ein Wert in einer Zelle des bearbeitbaren Rasters der Planung geändert wird und die Zelle nicht mehr im Fokus ist. Existiert jedoch der Handler OnChange für dieselbe Planung, wird der Handler OnSave nach dem Handler OnChange aufgerufen.

Der OnSave Handler wird vor dem eigentlichen Speichern des Feldes aufgerufen.

Notiz

• Für das bearbeitbare Raster der Planung löst jede Feldänderung die Ereignis-Handler OnChange und OnSave aus, sofern sie vorhanden sind.
• Das Speichern wird nicht ausgelöst, wenn ein Feld mit einer Fehlermeldung über die Client API im OnSave-Handler festgelegt wird. Für Benachrichtigungen in Bezug auf die Planung von Client APIs gehen Sie zur setNotification API in context.getFormContext().data.entity.attributes.getByName("Attribut Name").controls.get(0).
• Es gibt keine Zuordnung zwischen Attributen und dem OnSave-Handler, und jede Feldänderung löst den OnSave-Handler mit dem Kontextobjektparameter aus. Um das Attribut zu identifizieren, das den Handler ausgelöst hat, verwenden Sie die Funktion getIsDirty für das Attributobjekt. Weitere Informationen: context.getFormContext().data.entity.attributes.getByName("Attribut Name")

Im Folgenden sehen Sie ein Beispielszenario, das Sie mit dem Handler OnSave ausführen können:

• Blockieren Sie die automatische Speicherung auf der Grundlage des geschätzten Wertes mit preventDefault und öffnen Sie ein Ereignis in einem Fenster.

Context-Objekt für Ereignis Handler im bearbeitbaren Raster

Das Kontextobjekt enthält eine Reihe von APIs zur Durchführung von Vorgängen, die für einen zugrunde liegenden Datensatz in einer Planung spezifisch sind. Dieses Kontextobjekt wird als Parameter an die Ereignis-Handler in der bearbeitbaren Rasteransicht der Planung übergeben.

Die folgenden APIs werden unterstützt:

• context.getFormContext Methode
• context.getWebApiContext()
• context.getEventArgs().preventDefault()

Methode context.getFormContext

Gibt einen Verweis auf einen Datensatz im bearbeitbaren Raster der Planung zurück.

context.getFormContext().data.entity

Dies gibt ein Entitätsobjekt zurück und hat die folgenden Methoden:

Method	Rückgabetyp	Beschreibung des Dataflows
getEntityName()	String	Gibt eine Zeichenfolge zurück, die den logische Namen des Entitätsdatensatz darstellt.
getId()	String	Gibt eine Zeichenfolge zurück, die den GUID-Wert für den Datensatz darstellt.
attributes	List	Gibt eine Liste von Attributen zurück, die sich auf die Ansicht und eine Entität beziehen, die als Teil des bearbeitbaren Rasters für die Planung geladen ist. Sie können die folgenden Vorgänge durchführen: - context.getFormContext().data.entity.attributes.forEach - context.getFormContext().data.entity.attributes.getByName(arg) - context.getFormContext().data.entity.attributes.get(index)

context.getFormContext().data.entity.attributes.getByName("Attribut Name")

Dies gibt ein Attributobjekt zurück und hat die folgenden Methoden:

Method	Rückgabetyp	Beschreibung des Dataflows
getName()	String	Gibt eine Zeichenkette zurück, die den logischen Namen des Attributs darstellt.
getValue()	--	Ruft den Datenwert für ein Attribut ab.
getIsDirty()	Boolesch	Gibt einen booleschen Wert zurück, der angibt, ob es ungespeicherte Änderungen an dem Attributwert gibt.
controls	List	Gibt eine Liste von Steuerelementen für jedes Attributobjekt zurück. Anmerkung: Die Länge der Objektliste controls ist immer 1, und get(0) kann direkt verwendet werden.

context.getFormContext().data.entity.attributes.getByName("Attribut Name").controls.get(0)

Dies gibt ein Steuerelement zurück, das dem Attribut zugeordnet ist, und hat die folgenden Methoden:

Method	Rückgabetyp	Beschreibung des Dataflows
getDisabled()	Boolesch	Gibt zurück, ob das Steuerelement deaktiviert ist.
setDisabled(bool)	--	Legt den deaktivierten Wert (wahr oder falsch) für das Steuerelement fest.
setNotification(message: string, uniqueId?: string)	Boolesch	Zeigt eine Fehlermeldung für das Steuerelement an, um anzugeben, dass Daten ungültig sind. Bei dieser Methode wird neben dem Steuerelement in der Zelle ein rotes Symbol mit einem Kreuz angezeigt. Wenn Sie den Mauszeiger über das Symbol für Fehler bewegen, wird die entsprechende Nachricht angezeigt. Wenn Sie das Symbol für Fehler wählen, wird die Zeile neu geladen und alle Änderungen werden rückgängig gemacht. Die uniqueId wird verwendet, um diese Nachricht zu löschen, wenn Sie die clearNotification-Methode verwenden.
clearNotification(uniqueId?: string)	Boolesch	Entfernt eine Nachricht, die bereits für ein Steuerelement angezeigt wird. Wenn keine eindeutige ID angegeben wird, werden alle Benachrichtigungen für dieses Steuerelement entfernt.

Notiz

Wir empfehlen, dass die Funktionsnamen in der JavaScript-Datei mit den Namen der Ereignisse übereinstimmen und den Parameter des Kontextobjekts akzeptieren müssen.

Beispiel 1:

Wir erstellen JavaScript-Code, um ein bearbeitbares Raster für die Planung READ-ONLY zu machen. Außerdem rufen wir die Funktion OnRowLoad für jede Zeile auf, wenn das Raster erfolgreich geladen und gespeichert wurde.

function OnRowLoad(executionContext) {
    // Iterating through all attributes and disabling it.
    executionContext.getFormContext().data.entity.attributes.forEach(
        attribute => {
            attribute.controls.get(0).setDisabled(true);
        }
    )
}

Beispiel 2:

Wir erstellen JavaScript-Code, um alle Felder bis auf einige wenige nur für die Entität Verkaufschancen zu deaktivieren. Außerdem rufen wir die Funktion OnRowLoad für jede Zeile auf, wenn das Raster erfolgreich geladen und gespeichert wurde.

function OnRowLoad(executionContext) {

    // Get the logical name of the loaded entity as part of forecasting editable grid.
    var entityName = executionContext.getFormContext().data.entity.getEntityName();

    if (entityName === "opportunity") {

        // Defining the attributes list from opportunity that has to be enabled if loaded as part of view.
        var OPTY_ENABLE_ATTRS_LIST = ["name", "msdyn_forecastcategory", "actualvalue", "actualclosedate", "estimatedvalue", "estimatedclosedate"];

        executionContext.getFormContext().data.entity.attributes.forEach(
            attribute => {
                // Disabling all attributes other than OPTY_ENABLE_ATTRS_LIST
                if (!OPTY_ENABLE_ATTRS_LIST.includes(attribute.getName())) {
                    attribute.controls.get(0).setDisabled(true);
                }
            }
        )        
    }
}

Beispiel 3:

Wir erstellen JavaScript-Code, um verschiedene Entitäten für die geladene Konfiguration der Planung zu behandeln.

Für eine Verkaufschance-Entität wird das Skript Folgendes deaktivieren:

• Spalte Name
• actualRevenue und actualCloseData, wenn der forecastCategory-Wert best case, committed, omitted oder Pipeline ist.
• estimatedRevenue und estimatedCloseDate, wenn der forecastCategory-Wert gewonnen oder verloren ist.

In ähnlicher Weise deaktiviert das Script die Namensspalte für die Entität Konto und alle Spalten für andere Entitäten.

Außerdem rufen wir die Funktion OnRowLoad für jede Zeile auf, wenn das Raster erfolgreich geladen und gespeichert wurde.

function OnRowLoad(executionContext) {
		 
    // Get the logical name of the loaded entity as part of forecasting editable grid.
    var entityName = executionContext.getFormContext().data.entity.getEntityName();
    
    // If loaded logical name of entity in editable grid is opportunity.
    if (entityName === "opportunity") {
        
       var allAttrs = executionContext.getFormContext().data.entity.attributes;

       // Disable column name for all records if exists in the view.
       var nameAttr = allAttrs.getByName("name");
       if (nameAttr) {
           nameAttr.controls.get(0).setDisabled(true);
       }

       var fcatAttr = allAttrs.getByName("msdyn_forecastcategory");
       if (fcatAttr) {
           // Disable actualRevenue, actualCloseDate for forecastcategory Bestcase, committed, omitted, or pipeline.
           if (fcatAttr.getValue() <= 100000004 && fcatAttr.getValue() >= 100000001) {
                   var actualRevenueAttr = allAttrs.getByName("actualvalue");
                   var actualCloseDateAttr = allAttrs.getByName("actualclosedate");
                   if (actualRevenueAttr) actualRevenueAttr.controls.get(0).setDisabled(true);
                   if (actualCloseDateAttr) actualCloseDateAttr.controls.get(0).setDisabled(true);
           }
           // Disable estimatedRevenue, estimatedCloseDate for forecastCategory won or lost.
           else if (fcatAttr.getValue() == 100000005 || fcatAttr.getValue() == 100000006) {
                   var estimatedRevenueAttr = allAttrs.getByName("estimatedvalue");
                   var estimatedCloseDateAttr = allAttrs.getByName("estimatedclosedate");
                   if (estimatedRevenueAttr) estimatedRevenueAttr.controls.get(0).setDisabled(true);
                   if (estimatedCloseDateAttr) estimatedCloseDateAttr.controls.get(0).setDisabled(true);
           }
       }
   } 
   
   // Else disable name column, if loaded logical name of entity is Account.
   else if (entityName === "account"){
       var attrNameObj = executionContext.getFormContext().data.entity.attributes.getByName("name");
       if (attrNameObj) {
               attrNameObj.controls.get(0).setDisabled(true);
       }
   } 
   
   // For all other entities
   else {
       executionContext.getFormContext().data.entity.attributes.forEach(
           attribute => {
               attribute.controls.get(0).setDisabled(true);
           }
       )
   }
}

Beispiel 4:

Erstellen wir eine JavaScript-Validierungsdatei, die das Speichern blockiert und eine Fehlermeldung in der Spalte für den geschätzten Umsatz anzeigt, wenn der Wert unter 10 liegt. Außerdem entfernen wir die Fehlermeldung und lassen das Sichern zu, wenn der Wert der Spalte mit dem geschätzten Umsatz auf einen Wert größer oder gleich 10 korrigiert wird. Hier wird die Funktion OnChange aufgerufen, wenn der Wert eines beliebigen Feldes im bearbeitbaren Raster aktualisiert wird.

// OnChange function is invoked when any field's value is updated on the editable grid
function OnChange(executionContext) {

    let entity = executionContext.getFormContext().data.entity;

    // Verify the logical name of the entity and load as part of the editable grid.
    if (entity.getEntityName() === "opportunity") {

        // Verify estimated revenue value
        let estValAttr = entity.attributes.get("estimatedvalue");

        // Verify if this attribute exists within the grid view and changed
        if(estValAttr && estValAttr.getIsDirty()) 
        {
            if(estValAttr.getValue() < 10){

                // This will show an error icon next to the estimated revenue field. On hovering over the icon, the below provided message is displayed.
                // Any save attempts are blocked by the system until all notifications are cleared from the columns.
                estValAttr.controls.get(0).setNotification("Estimated revenue cannot be less than 10");
            }
            else{
                // Clearing notifications to save.
                estValAttr.controls.get(0).clearNotification();
            }
        }
    }
}

context.getWebApiContext()

Dieser gibt ein webApiContext-Objekt zurück und hat die folgenden Methoden:

Method	Beschreibung des Dataflows
retrieveRecord(entityLogicalName, id, options) then (successCallback, errorCallback);	Ruft einen Entitätsdatensatz ab. Weitere Informationen: Datensatz abrufen (Client API-Referenz)
updateRecord(entityLogicalName, id, data) then(successCallback, errorCallback);	Aktualisiert einen Entitätsdatensatz. Weitere Informationen: updateRecord (Client API Referenz)
createRecord(entityLogicalName, data) then(successCallback, errorCallback);	Erstellt einen Entitätsdatensatz. Weitere Informationen: createRecord (Client API Referenz)
deleteRecord(entityLogicalName, id) then(successCallback, errorCallback);	Löscht einen Entitätsdatensatz. Weitere Informationen: Datensatz löschen (Client API-Referenz)

context.getEventArgs().preventDefault()

Die Methode preventDefault() ist nur innerhalb des Ereignisses OnSave verfügbar. Der Aufruf dieser Methode innerhalb von OnSave verhindert, dass das Ereignis „Speichern“ fortgesetzt wird.

Beispiel:

Erstellen wir ein JavaScript-Beispiel, um das Raster der Verkaufschancen zu öffnen, das Ereignis für das automatische Speichern zu blockieren und eine Warnung zu öffnen, wenn der geschätzte Umsatz unter 10 liegt. Außerdem lassen wir das Ereignis „Automatisches Speichern“ zu, wenn der geschätzte Umsatz größer als oder gleich 10 ist.

// OnSave function will be invoked whenever grid attempts to save changes made to any field. 
function OnSave(executionContext){

    let entity = executionContext.getFormContext().data.entity;

    // Verify the logical name of the entity and load as part of the editable grid.
    if (entity.getEntityName() === "opportunity") {

        // Verify estimated revenue value
        var estValAttr = entity.attributes.get("estimatedvalue");

        if(estValAttr && estValAttr.getIsDirty() && estValAttr.getValue() < 10){

            // This call will prevent the save event from proceeding
            executionContext.getEventArgs().preventDefault(); 
            alert("Estimated revenue cannot be less than 10");

        }
    }
}

Siehe auch

Zugrunde liegende Datensätze anpassen