Freigeben über

Schreiben Ihres ersten Clientskripts

Bereit, Ihr erstes Clientskript zu schreiben, um es in Aktion zu sehen? Fangen wir an. Wir halten es einfach.

Ziel

Nach Abschluss dieser exemplarischen Vorgehensweise wissen Sie, wie Sie JavaScript-Code in modellgesteuerten Apps verwenden. Dieser Vorgang umfasst die folgenden allgemeinen Schritte:

  • Suchen oder erstellen Sie eine Lösung, zu der Sie Ihre Arbeit hinzufügen können
  • JavaScript Code für einen Geschäftsfall schreiben
  • Den Code als Webressource hochladen
  • Zuordnen Ihrer Webressource zu einem Formular
  • Formulare und Feldereignisse konfigurieren
  • Testen Ihres Codes

Schritt 1: Suchen oder erstellen Sie eine Lösung

Verwenden Sie Lösungen, um Anpassungen von einer Umgebung in eine andere zu übertragen. Schreiben und testen Sie Ihren JavaScript-Code in einer Entwicklungsumgebung als Teil einer nicht verwalteten Lösung. Wenn Sie mit dem Testen fertig sind, exportieren Sie die Lösung als verwaltete Lösung, und importieren oder installieren Sie sie in Ihrer Produktionsumgebung.

Möglicherweise steht Ihnen bereits eine vorhandene Lösung zur Verfügung. Die modellgesteuerte App, die Sie mit Ihrem Skript anpassen möchten, sollte bereits Teil einer Lösung sein. Sie können diese Lösung bearbeiten oder eine neue Lösung erstellen, die von einer anderen vorhandenen Lösung abhängt.

So erstellen Sie eine neue Lösung

  1. Wechseln Sie zu Power Apps.

  2. Wählen Sie im linken vertikalen Navigationsbereich Lösungen und dann Neue Lösung aus.

  3. Geben Sie im Flyout-Dialogfeld einen Anzeigenamen, Namen und Herausgeber ein.

    Die meisten Unternehmen verfügen über einen vorhandenen Herausgeber, den sie immer verwenden. Verwenden Sie diesen Herausgeber. Wenn Sie als Erste/r sind, erstellen Sie Ihren eigenen Publisher.

    Wählen Sie "Neuer Herausgeber" aus, um das Dialogfeld "Neuer Herausgeber " zu öffnen. Verwenden Sie in diesem Leitfaden einen Herausgeber mit dieser Definition:

    Formular zur Erstellung eines neuen Herausgebers mit den Informationen für den Beispielherausgeber

    Beachten Sie den Präfixwert. Dieser Wert sollte Ihr Unternehmen identifizieren. Verwenden Sie examplein diesem Fall .

    Diese Lösung ist die Lösung, die Sie in dieser exemplarischen Vorgehensweise verwenden.

    Lösungsformular für die Erste-Client-Script-Lösung

  4. Suchen Sie eine modellgesteuerte App oder fügen Sie sie Ihrer Lösung hinzu.

    Eine neue Lösung enthält keine modellgesteuerten Apps. Sie müssen eine vorhandene modellgesteuerte App hinzufügen oder eine neue erstellen.

    Anmerkung

    Stellen Sie für diese Schritt-für-Schritt-Anleitung sicher, dass die App die Konto-Tabelle enthält. Die folgenden Skripts und Anweisungen erwarten Felder, die in einem Formular für die Tabelle "Konto" gefunden wurden.

    Option A: Fügen Sie Ihrer Lösung eine vorhandene modellgesteuerte App hinzu

    1. Wählen Sie in Ihrer Lösung Vorhandene hinzufügen>App>Modellgesteuerte App.

    Vorhandene modellgesteuerte App hinzufügen

    1. Wählen Sie eine vorhandene App und dann "Hinzufügen" aus.

    Option B: Erstellen einer neuen modellbasierten App in Ihrer Lösung

    Wählen Sie in Ihrer Lösung Neue>App>modellgesteuerte App aus.

    Siehe das Tutorial Erstellen Sie Ihre erste modellgesteuerte App neu Erstellen Sie eine App, die die Account-Tabelle enthält.

Schritt 2: Schreiben des JavaScript Codes

Der erste Schritt besteht darin, das Geschäftsproblem zu identifizieren, das Sie mithilfe von Clientskripting beheben möchten. Wenn Sie das Problem identifizieren, schreiben Sie Ihren JavaScript-Code mit der benutzerdefinierten Geschäftslogik, die Ihr Geschäftsproblem behebt.

Modellgesteuerte Apps stellen keinen JavaScript-Editor bereit. Verwenden Sie ein externes Autorenwerkzeug, das Funktionen zur Verfügung stellt, die das Bearbeiten von JavaScript-Dateien gezielt unterstützen, wie z.B. Notepad++, Visual Studio Code, oder Microsoft Visual Studio.

In dieser exemplarischen Vorgehensweise wird der folgende JavaScript-Code verwendet:

// A namespace defined for the sample code
// As a best practice, you should always define 
// a unique namespace for your libraries
var Example = window.Example || {};
(function () {
    // Define some global variables
    var myUniqueId = "_myUniqueId"; // Define an ID for the notification
    var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
    var message = currentUserName + ": Your JavaScript code in action!";

    // Code to run in the form OnLoad event
    this.formOnLoad = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", myUniqueId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);
    }

    // Code to run in the column OnChange event 
    this.attributeOnChange = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        var accountName = formContext.getAttribute("name").getValue();
        if (accountName.toLowerCase().search("contoso") != -1) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    }

    // Code to run in the form OnSave event 
    this.formOnSave = function () {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    }
}).call(Example);

Kopieren Sie diesen Code in eine Textdatei, und speichern Sie ihn unter Example-form-script.js.

Ausführliche Code Erklärung

Sehen Sie sich den Code detailliert an:

  • Namespace definieren: Das Schreiben des Codes beginnt mit der Definition eines Namespaces in Ihrem benutzerdefinierten Skript. Erstellen Sie als bewährte Methode immer namespaced JavaScript-Bibliotheken, um zu vermeiden, dass Ihre Funktionen von Funktionen in einer anderen Bibliothek außer Kraft gesetzt werden.

    var Example = window.Example || {};

    In diesem Fall können Sie alle Funktionen, die in dieser Bibliothek definiert sind, als Example.[functionName] verwenden. Wählen Sie einen Namespace aus, der ihrem Namen des Lösungsherausgebers entspricht.

  • Definieren sie globale Variablen: Im folgenden Abschnitt werden einige globale Variablen definiert, die im Skript verwendet werden sollen. Sie können global auf Kontextinformationen zugreifen, indem Sie die Xrm.Utility.getGlobalContext-Methode verwenden.

    // Define some global variables
var myUniqueId = "_myUniqueId"; // Define an ID for the notification
var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
var message = currentUserName + ": Your JavaScript code in action!";

  • Funktion, die für das OnLoad-Ereignis ausgeführt werden soll: Dieser Abschnitt enthält die Funktion, die beim Laden des Kontoformulars ausgeführt wird. Beispielsweise, wenn Sie einen neuen Firmendatensatz erstellen oder einen vorhandenen Firmendatensatz öffnen.

    Die Example.formOnLoad-Funktion verwendet die executionContext-Parameter, um das formContext-Objekt zu erhalten. Wenn Sie den Code mithilfe des Formularereignisses später anfügen, wählen Sie die Option aus, um den Ausführungskontext an diese Funktion zu übergeben.

    Diese Funktion zeigt eine Benachrichtigung auf Formularebene mithilfe der formContext.ui.setFormNotification-Methode an.

    Schließlich verwendet diese Funktion die JavaScript-Methode setTimeOut, um die Ausführung der formContext.ui.clearFormNotification-Methode zu verzögern, um die Benachrichtigung nach 5 Sekunden zu löschen.

    // Code to run in the form OnLoad event
this.formOnLoad = function (executionContext) {
    var formContext = executionContext.getFormContext();

    // Display the form level notification as an INFO
    formContext.ui.setFormNotification(message, "INFO", myUniqueId);

    // Wait for 5 seconds before clearing the notification
    window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);        
}

  • Funktion, die für das OnChange-Ereignis ausgeführt werden soll: Ordnen Sie die Funktion der Example.attributeOnChange Spalte " Kontoname " im Kontoformular zu, sodass sie nur ausgeführt wird, wenn Sie den Kontonamenwert ändern.

    Diese Funktion führt eine von Groß- und Kleinschreibung unabhängige Suche nach „Contoso“ im Konto name durch und legt, falls vorhanden, automatisch Werte für die Spalten websiteurl, telephone1 und description im Formular für das Konto fest.

    // Code to run in the column OnChange event 
this.attributeOnChange = function (executionContext) {
    var formContext = executionContext.getFormContext();

    // Automatically set some column values if the account name contains "Contoso"
    var accountName = formContext.getAttribute("name").getValue();
    if (accountName.toLowerCase().search("contoso") != -1) {
        formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
        formContext.getAttribute("telephone1").setValue("425-555-0100");
        formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
    }
}

  • Funktion, die für das OnSave-Ereignis ausgeführt werden soll: Die Example.formOnSave Funktion zeigt ein Warnungsdialogfeld mithilfe der Xrm.Navigation.openAlertDialog-Methode an. Dieses Dialogfeld zeigt eine Meldung mit einer OK-Schalfläche an: Der Benutzer kann die Benachrichtigung schließen, indem er "OK" auswählt.

    Anmerkung

    Diese Funktion verwendet nicht den Ausführungskontext, da die Xrm.Navigation-Methoden sie nicht benötigen.

    // Code to run in the form OnSave event 
this.formOnSave = function () {
    // Display an alert dialog
    Xrm.Navigation.openAlertDialog({ text: "Record saved." });
}

Schritt 3: Den Code als Webressource hochladen

Nachdem Ihr Code bereit ist, laden Sie ihn in Ihre Lösung hoch.

  1. Wählen Sie in Ihrer Lösung "Neue>>" aus.

    Hinzufügen einer neuen Webressourcen zu Ihrer Lösung

  2. Wählen Sie im Dialogfeld "Neue Webressource " die Option "Datei auswählen " und dann die Datei aus, die Example-form-script.js Sie zuvor gespeichert haben.

  3. Geben Sie den Anzeigenamen, den Namen und optional eine Beschreibung ein. Stellen Sie sicher, dass der TypJavaScript (JS) ist.

    Neuer Webressourcendialog zum Erstellen eines Beispielformularskripts

    Anmerkung

    • Der Name weist ein Präfix auf, das dem Anpassungspräfix des Lösungsherausgebers entspricht. Es gibt andere Möglichkeiten zum Erstellen von Webressourcen, aber das Erstellen einer Webressource auf diese Weise stellt sicher, dass die Webressource Teil Ihrer Lösung ist.
    • Der Name der Webressource lautet example_example-form-script.

Schritt 4: Ihre Webressource einem Formular zuordnen

  1. Wählen Sie in Ihrer Lösung Objekte>Apps>Ihre App aus, und klicken Sie auf Bearbeiten.

    Bearbeiten Sie die App in der Lösung.

  2. Erweitern Sie „Konto“ und wählen Sie das Formular „Konto“ aus. Klicken Sie rechts neben dem Informationsformular auf die Auslassungspunkte (...), und wählen Sie "Bearbeiten" aus.

    Bearbeiten Sie das Formular mit Kontoinformationen

  3. Wählen Sie im linken Navigationsbereich Formularbibliotheken aus, und klicken Sie dann auf Bibliothek hinzufügen.

    Bibliothek zum Formular hinzufügen

  4. In dem JavaScript-Bibliothek hinzufügen-Dialog suchen Sie nach dem Namen der von Ihnen erstellten JavaScript-Webressource: Example Script.

    JavaScript-Bibliothek-Dialog hinzufügen

  5. Wählen Sie die Beispiel-Skript-Webressource aus, und klicken Sie auf Hinzufügen.

Schritt 5: Formular- und Feldereignis konfigurieren

  1. Wählen Sie die Registerkarte Ereignisse aus.

    Formular-Ereignishandler

Konfigurieren des Formular-On Load-Ereignisses

  1. Wählen Sie On Load-Ereignishandler aus, und klicken Sie auf + Ereignishandler.

    Konfigurieren Sie den Formular-Handler beim Laden

    Stellen Sie sicher, dass die folgenden Einstellungen korrekt sind:

    • Der Ereignistyp ist On Load.
    • Die example_example-form-script-Bibliothek ist ausgewählt.
    1. Geben Sie im Feld Funktion den Namen der Funktion ein. Geben Sie in diesem Fall die Zeichenfolge Example.formOnLoadein.
    2. Wählen Sie Passausführungskontext als ersten Parameter aus.
    3. Klicken Sie auf Fertig.

Formular beim Speichern-Ereignis konfigurieren

  1. Wählen Sie den On Save-Ereignishandler und dann +Ereignishandler aus.

    Handler für Formular On Save konfigurieren

    Stellen Sie sicher, dass die folgenden Einstellungen korrekt sind:

    • Der Ereignistyp ist On Save.
    • Die example_example-form-script-Bibliothek ist ausgewählt.
    1. Geben Sie im Feld Funktion den Namen der Funktion ein. Geben Sie in diesem Fall die Zeichenfolge Example.formOnSaveein.

      Anmerkung

      Sie müssen den Pass-Ausführungskontext nicht als ersten Parameter für diese Funktion auswählen, da er nicht verwendet wird.

    2. Wählen Sie Fertig aus.

Konfigurieren des "On Change"-Ereignisses für das Feld

  1. Wählen Sie das Feld Kontoname und die Registerkarte Ereignisse aus.

    Ereignisse für das Feld

  2. Wählen Sie den On Change-Ereignishandler aus, und klicken Sie auf + Ereignishandler.

    Feld OnChange-Handler konfigurieren

    Stellen Sie sicher, dass die folgenden Einstellungen korrekt sind:

    • Der Ereignistyp ist On Change.
    • Die example_example-form-script-Bibliothek ist ausgewählt.
    1. Geben Sie im Feld Funktion den Namen der Funktion ein. In diesem Fall Example.attributeOnChange.
    2. Wählen Sie Ausführungskontext als ersten Parameter übergeben aus.
    3. Wählen Sie Fertig aus.

Speichern und veröffentlichen Sie die Änderungen

Speichern Sie das Formular, und klicken Sie auf "Veröffentlichen".

Schritt 6: Testen Ihres Codes

Aktualisieren Sie Ihren Browser, um sicherzustellen, dass Ihre Änderungen in Ihrer modellgesteuerten App-Instanz wirksam werden.

So testen Sie Ihren Code:

  1. Wechseln Sie zu Power Apps.

  2. Wählen Sie im linken Navigationsbereich "Apps" aus.

  3. Öffnen Sie die modellgesteuerte App, die Sie gerade bearbeitet haben, oder wählen Sie sie aus, und wählen Sie "Wiedergeben" aus.

    Die App zum Testen bearbeiten

On Load-Funktion des Formulars testen

  1. Wählen Sie einen beliebigen Kontodatensatz in der Liste aus, um ihn zu öffnen.

  2. Vergewissern Sie sich, dass die Benachrichtigung angezeigt wird.

    Benachrichtigung beim Laden des Formulars

  3. Vergewissern Sie sich, dass die Benachrichtigung nach 5 Sekunden verschwindet.

Feld 'On Change'-Funktion testen

  1. Bearbeiten Sie den Kontonamen, sodass er „Contoso“ enthält, und gehen Sie mit TAB zur nächsten Spalte.

  2. Überprüfen Sie die in den Spalten Haupttelefon, Webseite und Beschreibung festgelegten erwarteten Werte.

    Bei Feldänderung festgelegte Werte

Formular On Save-Funktion testen

  1. Wählen Sie Speichern aus.

  2. Stellen Sie sicher, dass im Warnungsdialogfeld die Meldung angezeigt wird, die Sie in Ihrem Code konfiguriert haben.

    Warndialog beim Speichern des Formulars

  3. Wählen Sie "OK" aus, um die Warnung zu schließen.

Debuggen von JavaScript-Code für modellbasierte Apps
Ereignisse in Formularen und in Rastern in modellgesteuerten Apps
Form OnLoad-Ereignis
Formular OnSave Ereignis (Client-API-Referenz) in modellgesteuerten Apps
OnChange-Ereignis der Spalte (Client-API-Referenz)

  • Last updated on