Freigeben über

Xrm.Utility (clientseitige Referenz)

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Das Xrm.Utility-Objekt stellt eine Sammlung nützlicher Informationen bereit, die nicht direkt mit der aktuellen Seite zusammenhängen.

Diese Funktionen in jeder Anwendungsseite verfügbar, die Skripting unterstützt. Sie können sie in Formularskripten oder in Menübandbefehlen verwenden. Für HTML-Webressourcen sind sie verfügbar, wenn Sie sie in die ClientGlobalContext.js.aspx-Seite einschließen. Weitere Informationen finden Sie unter GetGlobalContext function und ClientGlobalContext.js.aspx (clientseitige Referenz).

Funktionen

  • Dialoge
    Verwenden Sie alertDialog und confirmDialog, um den Beutzern Nachrichten anzuzeigen und Code basierend auf ihrer Antwort auszuführen. Diese Funktionen müssen mit mobilen Dynamics 365-Clients (Smartphones und Tablets) anstelle der window.alert- und window.confirm-Methoden verwendet werden.

  • Native Gerätefunktionen (mobile Dynamics 365-Clients)
    Verwenden Sie getBarcodeValue und getCurrentPosition, um die nativen Gerätefunktionen mobiler Geräte zu verwenden, um den Barcodewert abzurufen, oder die aktuelle Position des Geräts zu erhalten.

  • isActivityType
    Ermitteln Sie, ob eine Entität eine Aktivitätsentität ist.

  • openEntityForm
    Öffnet ein Entitätsformular.

  • openQuickCreate
    Verwenden Sie diese Funktion für Microsoft Dynamics CRM Online 2015-Update 1 oder höher, um ein neues Schnellerfassungsformular zu öffnen. Sie können diese Funktion verwenden zum Festlegen von Standardwerten mithilfe von Attributzuordnungen oder für bestimmte Attribute. Wenn der Benutzer den Datensatz speichert, können Sie einen Verweis auf den erstellten Datensatz erfassen.

  • openWebResource
    Öffnet eine HTML-Webressource.

Dialoge

Zwei Dialogtypen stehen zur Verfügung: alertDialog und confirmDialog. Diese sind für die Verwendung mit Skripts enthalten, die mit mobilen Dynamics 365-Clients (Smartphones und Tablets) funktionieren. Mobile Dynamics 365-Clients lassen die Verwendung von JavaScript-Funktionen wie window.alert und window.confirm, die den Codefluss blockieren, nicht zu. Verwenden Sie diesen Methoden, wenn Sie eine Nachricht für Benutzer anzeigen müssen. der entscheidende Unterschied ist, dass diese Methoden Code nicht blockieren, bis sie ein Benutzer sie schließt. Sie enthalten einen Rückruffunktionsparameter, um anzuzeigen, welcher Code abhängig von der Antwort des Benutzers ausgeführt werden soll.

Hinweis

In mobilen Dynamics 365-Clients (Smartphones und Tablets) wird jede Verwendung der window.alert -Methode außer Kraft gesetzt, um Xrm.Utility.alertDialog ohne Rückruf zu verwenden. Hierdurch wird die Nachricht angezeigt, aber die Ausführung von Code nicht blockiert, wie bei window.alert. Diese Zuordnung von window.alert zu Xrm.Utility.alertDialog in mobilen Dynamics 365-Clients ist veraltetet und wird in der nächsten Hauptversion entfernt werden. Sie sollten Code, über den Sie jetzt verfügen, zur Verwendung von Xrm.Utility.alertDialog statt window.alert migrieren.

alertDialog

Zeigt ein Dialogfeld an, das eine anwendungsdefinierte Meldung enthält.

Xrm.Utility.alertDialog(message,onCloseCallback)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    Meldung

    Zeichenfolge

    Ja

    Der Text der Meldung, die im Dialogfeld angezeigt wird.

    onCloseCallback

    Funktion

    Nein

    Eine Funktion, die ausgeführt wird, wenn auf die OK-Schaltfläche geklickt wird.

  • Anmerkungen
    Diese Methode ist nur für Aktualisierte Entitäten verfügbar.

confirmDialog

Zeigt ein Bestätigungsdialogfeld an, das eine optionale Nachricht und die Schaltflächen OK und Abbrechen enthält.

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    Meldung

    Zeichenfolge

    Ja

    Der Text der Meldung, die im Dialogfeld angezeigt wird

    yesCloseCallback

    Funktion

    Nein

    Eine Funktion, die ausgeführt wird, wenn auf die OK-Schaltfläche geklickt wird.

    noCloseCallback

    Funktion

    Nein

    Eine Funktion, die ausgeführt wird, wenn auf die Abbrechen-Schaltfläche geklickt wird.

  • Anmerkungen
    Diese Methode ist nur für Aktualisierte Entitäten verfügbar.

Native Gerätefunktionen (mobile Dynamics 365-Clients)

Nutzen Sie diese Methoden für Dynamics 365 für Smartphones- und Dynamics 365 für Tablets-Clients, um die Benutzerfreundlichkeit für mobile Nutzer im Vertrieb, im Außendienst und in anderen Bereichen zu verbessern.

Hinweis

Diese Methoden wurden mit Update für Dynamics 365 (online und lokal), Dezember 2016 eingeführt.

getBarcodeValue

Gibt die Barcodeinformationen, wie eine Produktzahl zurück, gescannt mithilfe der Gerätekamera.

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    successCallback

    Funktion

    Ja

    Ein Funktion, die bei der Rückgabe des Barcodewerts aufgerufen wird.

    errorCallback

    Funktion

    Ja

    Eine Funktion zum Aufrufen, wenn der Vorgang fehlschlug. Ein Fehlerobjekt mit der message-Eigenschaft wird übergeben, das die Fehlerdetails beschreibt.

  • Anmerkungen
    Damit die getBarcodeValue-Methode funktioniert, müssen die mobilen Dynamics 365-Clients Zugriff auf die Gerätenkamera haben (standardmäßig aktiviert).

  • Beispiel
    Im folgenden Beispielcode wird gezeigt, wie Sie diese Methode verwenden.

    Xrm.Utility.getBarcodeValue().then(
    function (result) {
        Xrm.Utility.alertDialog("Barcode value: " + result);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

getCurrentPosition

Gibt den aktuellen Standort mithilfe der Gerätegeolokalisierungsfunktion zurück.

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    successCallback

    Funktion

    Ja

    Ein Funktion, die bei der Rückgabe der aktuellen Geostandortinformationen aufgerufen wird. Ein Geolokalisierungsobjekt mit folgenden Attributen wird an die Funktion übergeben.

    • coords: Enthält einen Satz geografischer Koordinaten mit entsprechender Genauigkeit sowie einen Satz anderer optionaler Attribute wie die Höhe und Geschwindigkeit.

    • timestamp: Stellt die Uhrzeit dar, zu der das Objekt erhalten wurde und ist ein DOMTimeStamp.

    errorCallback

    Funktion

    Ja

    Eine Funktion zum Aufrufen, wenn der Vorgang fehlschlug. Es wird ein Objekt mit den folgenden Eigenschaften übergeben:

    • code: Zahl. Der Fehlercode.

    • message: Zeichenfolge. Lokalisierte Meldung, welche die Fehlerdetails beschreibt.

    Wenn der die Lokalisierungseinstellung des Benutzers nicht auf dem Mobilgerät aktiviert ist, zeigt die Fehlermeldung dies an. Falls Sie eine frühere Version des mobilen Dynamics 365-Clients verwenden, oder wenn die Geolokalisierungsfunktion nicht auf mobilen Geräten verfügbar ist, wird null an den Fehler-Callback übergeben.

  • Anmerkungen
    Damit die getCurrentPosition-Methode funktioniert, muss Geolokalisierungsfunktion auf dem Gerät aktivier sein und der mobilen Dynamics 365-Client muss die Berechtigungen besitzen, auf den Gerätenspeicherort zuzugreifen (standardmäßig nicht aktiviert).

  • Beispiel
    Im folgenden Beispielcode wird gezeigt, wie Sie diese Methode verwenden.

    Xrm.Utility.getCurrentPosition().then
    (function (location) {
        Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
           ", Longitude: " + location.coords.longitude);
    },
    function (error) {
        Xrm.Utility.alertDialog(error.message);
    })

isActivityType

Ermitteln Sie, ob eine Entität eine Aktivitätsentität ist.

Xrm.Utility.isActivityType(entityName)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    entityName

    Zeichenfolge

    Ja

    Der logische Name einer Entität.

  • Rückgabewert

    Typ

    Beschreibung

    Boolean

    True, wenn die Entität eine Aktivitätsentität ist, sonst false.

openEntityForm

Öffnet ein Entitätsformular für einen neuen oder vorhandenen Entitätsdatensatz mithilfe der als Parameter festgelegten Optionen.

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    Name

    Zeichenfolge

    Ja

    Der logische Name der Entität.

    id

    Zeichenfolge

    Nein

    Die Zeichenfolgendarstellung eines eindeutigen Bezeichners oder des zu öffnenden Datensatzes im Formular. Falls nicht festgelegt, wird ein Formular geöffnet, um einen neuen Datensatz zu erstellen.

    Parameter

    Objekt

    Nein

    Ein Wörterbuchobjekt, das dem Formular zusätzliche Parameter übergibt. Ungültige Parameter führen zu einem Fehler.

    Gültige zusätzliche Abfragezeichenfolgenparameter sind:

    windowOptions

    Objekt

    Nein

    Verwenden Sie bei Microsoft Dynamics CRM Online 2015-Update 1 oder höher diesen optionalen Parameter in der Webanwendung, um zu steuern, wie das Formular geöffnet wird. Ein Formular kann in einem neuen Fenster geöffnet werden, indem Sie ein Wörterbuchobjekt übergeben, dessen Boolesche openInNewWindow-Eigenschaft auf true festgelegt ist.

    Dieser Parameter wird in mobilen Dynamics 365-Clients (Smartphones und Tablets) ignoriert.

  • Anmerkungen
    Mit dieser Funktion können Sie sicherstellen, dass Benutzer nicht aufgefordert werden, sich unter bestimmten Umständen erneut anzumelden.

  • Beispiele
    Öffnen Sie einen neuen Firmendatensatz mithilfe des Standardformulars

    Xrm.Utility.openEntityForm("account");

    Öffnen Sie einen bestehenden Firmendatensatz mithilfe des Standardformulars

    Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");

    Öffnen eines neuen Firmendatensatzes mit einem bestimmten Formular und Einstellung von Standardwerten

    var parameters = {};
parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
parameters["name"] = "Test";
parameters["telephone1"] = "(425) 555-1234";
Xrm.Utility.openEntityForm("account", null, parameters);

    Öffnen Sie einen neuen Firmendatensatz mithilfe des Standardformulars in einem neuen Fenster

    var windowOptions = {
 openInNewWindow: true
};
Xrm.Utility.openEntityForm("account",null,null,windowOptions);

openQuickCreate

Verwenden Sie diese Funktion für Microsoft Dynamics CRM Online 2015-Update 1 oder höher, um ein neues Schnellerfassungsformular zu öffnen. Sie können diese Funktion verwenden zum Festlegen von Standardwerten mithilfe von Attributzuordnungen oder für bestimmte Attribute. Wenn der Benutzer den Datensatz speichert, können Sie einen Verweis auf den erstellten Datensatz erfassen.

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    entityLogicalName

    Zeichenfolge

    Ja

    Der logische Name der zu erstellenden Entität

    createFromEntity

    Suche

    Nein

    Gibt einen Datensatz an, der Standardwerte basierend auf zugeordneten Attributwerten bereitstellt.

    Ein Such-Objekt bietet folgende String-Eigenschaften:

    • entityType: der logische Name der Entität.

    • id: Eine Zeichenfolgendarstellung eines GUID-Werts für den Datensatz.

    • name: der primäre Attributwert des Datensatzes.

    Parameter

    Objekt

    Nein

    Ein Wörterbuchobjekt, das dem Formular zusätzliche Abfragezeichenfolgeparameter übergibt. Ungültige Abfragezeichenfolgenparameter führen zu einem Fehler

    Gültige zusätzliche Abfragezeichenfolgenparameter sind:

    successCallback

    Funktion

    Nein

    Die Funktion, die aufgerufen wird, wenn ein Datensatz erstellt wird. Dieser Funktion wird ein Objekt als Parameter übergeben. Dieses Objekt enthält eine savedEntityReference-Eigenschaft mit den folgenden Eigenschaften, um den erstellten Datensatz zu ermitteln:

    • entityType: der logische Name der Entität.

    • id: Eine Zeichenfolgendarstellung eines GUID-Werts für den Datensatz.

    • name: der primäre Attributwert des erstellten Datensatzes.

    errorCallback

    Funktion

    Nein

    Eine Funktion zum Aufrufen, wenn der Vorgang fehlschlug.

    Es wird ein Objekt mit den folgenden Eigenschaften übergeben:

    • errorCode: Number. Der Fehlercode.

    • message: String. Eine loklisierte Fehlermeldung.

  • Anmerkungen
    Diese Funktion ist nur für Microsoft Dynamics CRM Online 2015-Update 1 oder höher verfügbar.

    Es gibt ein Limit von zehn geschachtelten Schnellerfassungsformularen in der Webanwendung. Ist dieser Grenzwert überschritten, öffnet diese Funktion das vollständige Entitätsformular anstelle des Schnellerfassungsformulars.

  • Beispiel
    Wenn dieser Code in einem Firmenentitätsformular ausgeführt wird, erstellt ein Schnellerfassungsformular eine neue untergeordnete Firma mit einem standardmäßigen Namen, der so festlegt ist, dass er den Namen der übergeordneten Firma enthält.

    var thisAccount = {
    entityType: "account",
    id: Xrm.Page.data.entity.getId()
};
var callback = function (obj) {
    console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
}
var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
    console.log(error.message);
});

    Wenn dieser Code mit Browserentwicklertools (F12-Tools) ausgeführt wird, stellt das Folgende die Ausgabe an die Konsole dar, wenn die Ausführung im Rahmen einer Firma namens "A. Datum Corporation (sample)" erfolgt und der Benutzer den Standardnamen, der für die neue untergeordnete Firma festgelegt wurde, nicht ändert.

    Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}

openWebResource

Öffnet eine HTML-Webressource.

Hinweis

Diese Funktion wird für mobile Dynamics 365-Clients (Smartphones und Tablets) und den interaktiven Servicehub nicht unterstützt.

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

  • Parameter

    Name

    Typ

    Erforderlich

    Beschreibung

    webResourceName

    Zeichenfolge

    Ja

    Der Name der zu öffnenden HTML-Webressource.

    webResourceData

    Zeichenfolge

    Nein

    Daten, die in den Datenparameter übergeben werden.

    width

    Anzahl

    Nein

    Die Breite des zu öffnenden Fensters in Pixeln.

    height

    Anzahl

    Nein

    Die Höhe des zu öffnenden Fensters in Pixeln.

  • Rückgabewert
    Fensterobjekt.

  • Anmerkungen
    Eine HTML-Webressource kann die Parameterwerte annehmen, die in Parameter an HTML-Webressourcen übergeben beschrieben sind. Diese Funktion dient nur zum Übergeben des optionalen Datenparameters. Um Werte für weitere gültige Parameter zu übergeben, müssen Sie sie an den webResourceName-Parameter anfügen.

  • Beispiele
    Öffnen einer HTML-Webressource namens "new_webResource.htm"

    Xrm.Utility.openWebResource("new_webResource.htm");

    Öffnen einer HTML-Webressource und ein einzelnes Element von Daten für den Datenparameter

    Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");

    Öffnen einer HTML-Webressource zum Übergeben mehrerer Werte über den Datenparameter

    var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
Xrm.Utility.openWebResource("new_webResource.htm",customParameters);

    Hinweis

    Diese Werte müssen aus dem Wert des Datenparameters in der HTML-webressource extrahiert werden. Weitere Informationen finden Sie unter Beispiel: Mehrere Werte über den Datenparameter an eine Webressource übergeben.

    Öffnen einer HTML-Webressource mit den von HTML-Webressourcen erwarteten Parametern

    Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");

    Weitere Informationen finden Sie unter Parameter an HTML-Webressourcen übergeben.

    Öffnen einer HTML-Webressource, die Höhe und Breite festlegt

    Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);

Siehe auch

Cclientseitige Programmierreferenz
Öffnen von Formularen, Ansichten, Dialogen und Berichten mit einer URL
Festlegen von Feldwerten mithilfe von Parametern, die an ein Formular übergeben werden
Ein Formular konfigurieren, um benutzerdefinierte Abfragezeichenfolgenparameter zu akzeptieren.
Kurzübersicht zum Formularskripting
Schreiben von Code für Microsoft Dynamics 365-Formulare
Verwenden des Xrm.Page-Objektmodells

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright