Freigeben über

Xrm.Page.ui-Steuerelement (clientseitige Referenz)

  • Artikel

 

Veröffentlicht: Januar 2017

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

Das control-Objekt bietet Methoden, um die Darstellung und das Verhalten eines Steuerelements zu ändern und das entsprechende Attribut zu identifizieren.

Der Zugriff auf Steuerelemente erfolgt mit folgenden Sammlungen: Xrm.Page.ui.Steuerelemente, Xrm.Page.ui Section.Steuerelemente oder Xrm.Page.data.entity Attribute.Steuerelemente. Die Xrm.Page.getControl-Methode ist eine Verknüpfungsmethode zum Zugreifen auf Xrm.Page.ui.controls.get.

Die Syntaxbeispiele in dieser Thema zeigen die Verwendung der Xrm.Page.getControl-Methode für den Zugriff auf ein Steuerelement. Die Art des Steuerelements ist abhängig von den Argumenten, die an die Methode übergeben werden. Der args-Parameter zum Zugreifen auf ein einzelnes Steuerelement muss entweder der Name vom Steuerelement oder Index sein.

Wenn ein Formular ein Geschäftsprozessfluss-Steuerelement in der Kopfzeile anzeigt, werden zusätzliche Steuerelemente für jedes Attribut hinzugefügt, das im Geschäftsprozessfluss angezeigt wird. Diese Steuerelemente enthalten einen eindeutigen Namen, zum Beispiel: header_process_<attribute name>.

Hinweis

Nur auf Steuerelemente in der aktiven Phase des Geschäftsprozessflusses kann per Name auf diese Weise zugegriffen werden.

Steuerelemente, die in der Formularkopfzeile angezeigt werden, sind zugänglich und haben einen eindeutigen Namen, wie z. B.: header_<attribute name>.

Für Steuerelemente, die an Attribute gebunden sind, erfolgt der Zugriff auf Steuerelemente normalerweise über die Xrm.Page.data.entity Attribute.Steuerelemente-Sammlung.

Die neuen benutzerdefinierten Steuerelemente für Dynamics 365 mobile Clients (Smartphones und Tablets) unterstützen alle Steuerelementeigenschaften und -methoden, mit Ausnahme der folgenden: Methoden der automatischen Vervollständigung, getValueKeypress-Methoden und Suchsteuerelementmethoden und -ereignisse.

Mit der Veröffentlichung von Microsoft Dynamics CRM Online 2016-Update 1 und Microsoft Dynamics CRM 2016 Service Pack 1 (lokal) werden jetzt die folgenden Arten von Zeitgebersteuerelementen im neuen Formularrenderingmodul unterstützt (auch "Turbo-Formulare" genannt ): Methoden getControlType, getName, getParent, Beschriftung, refreshSichtbar.

Steuerelementeigenschaften und -methoden

  • Methoden der automatischen Vervollständigung
    Konfigurieren der Oberfläche zur automatischen Vervollständigung in Textsteuerelementen in Dynamics 365-Formularen. Diese Methoden wurden mit Dynamics 365 eingeführt.

  • Deaktiviert
    Mit den getDisabled- and setDisabled-Methoden können Sie den Zustand erkennen und Steuerelemente aktivieren bzw. deaktivieren.

  • getAttribute
    Rufen Sie das Attribut ab, an das das Steuerelement gebunden ist.

  • getControlType
    Abrufen von Informationen zum Typ des Steuerelements.

  • getName
    Abrufen des Namens des Steuerelements.

  • getParent
    Abrufen des Abschnittsobjekts, in dem das Steuerelement vorhanden ist.

  • getValue
    Ruft den neuesten Wert für ein Steuerelement ab, wenn Benutzer ein Zeichen in ein bestimmtes Text- oder Zahlenfeld eingeben. Diese Methode wurde in Dynamics 365 eingeführt.

  • Keypress-Methoden
    Hinzufügen, Entfernen oder Duirchführten einer Aufgabe, wenn der Benutzer eine Taste in einem Steuerelement drückt. Diese Methoden wurden mit Dynamics 365 eingeführt.

  • Methoden für Wissensdatenbank-Suchsteuerelemente
    Diese Methoden sind nur für das Suchsteuerelement für die Wissensdatenbank in einer Dynamics 365-Instanz verfügbar, bei der die Funktion Wissensmanagement aktiviert ist.

    Informationen zu diesem Steuerelement finden Sie unter Suchsteuerelement für die Wissensdatenbank (clientseitige Referenz).

  • Beschriftung
    Abrufen oder Ändern der Beschriftung für ein Steuerelement mit den getLabel- und setLabel-Methoden.

  • Suchsteuerelementmethoden und -ereignisse
    Steuern Sie die Ergebnisse, die für einen Benutzer zur Auswahl angezeigt werden, wenn sie den Wert eines Suchsteuerelements festlegen, mithilfe der addCustomFilter, addCustomView, getDefaultView oder setDefaultView-Methoden.

    Sie können Ereignishandler für die PreSearch-Ereignis mithilfe der addPreSearch- und removePreSearch-Methoden hinzufügen oder entfernen.

  • Benachrichtigung
    Anzeigen und Entfernen von Benachrichtigungen für Benutzer über ein Steuerelement mithilfe der setNotification, addNotification und clearNotification -Methoden.

  • OptionSet-Steuerelement-Methoden
    Ändern der Optionen, die in OptionSet-Steuerelementen angezeigt werden, mithilfe der addOption-, clearOptions- und removeOption-Methoden.

  • ShowTime
    Verwenden Sie setShowTime, um anzugeben, ob ein Datumssteuerelement den Zeitteil des Datums anzeigen sollte, und getShowTime, um zu bestimmen, ob der Zeitteil des Datums aktuell angezeigt wird.

  • Unterraster-Steuerelementmethoden
    Für Organisationen mit CRM Online 2015-Update 1 gibt es neue Funktionen, um mit Unterrastersteuerelementen zu arbeiten.Weitere Informationen:Rasterobjekte (schreibgeschützt)und -Methoden (clientseitige Referenz)

    Bei anderen Organisationen ist die refresh-Methode die einzige eindeutige Methode, die für Unterrastersteuerelemente verfügbar ist. Diese Methode aktualisiert die Daten, die im Unterraster angezeigt werden.

  • Sichtbar
    Legen Sie fest, welche Steuerelemente sichtbar sind und zeigen Sie sie an oder verbergen Sie sie, mithilfe der getVisible- und setVisible-Methoden.

  • Webressourcen- und IFRAME-Steuerelementmethoden
    Interagieren mit Webressourcen- und IFRAME-Steuerelementen, mithilfe der getData-, setData-, getInitialUrl-, getObject-, setSrc- und getSrc-Methoden.

Methoden der automatischen Vervollständigung

Verwenden Sie die showAutoComplete- und hideAutoComplete-Methoden zum Konfigurieren der automatischen Vervollständigung in den Textkontrollen in CRM-Formularen.

Einen JavaScript-Beispielcode, der die Funktion der automatischen Vervollständigung veranschaulicht, finden Sie unter Beispiel: Automatische Vervollständigung in Dynamics 365-Steuerelementen

Hinweis

Diese Methoden werden für mobile Dynamics 365-Clients (Smartphones oder Tablets) und den interaktiven Servicehub nicht unterstützt. Diese Methoden nur für Aktualisierte Entitäten verfügbar.

showAutoComplete

Verwenden Sie diese Funktion, um bis zu 10 übereinstimmende Zeichenfolgen in einer Dropdownliste anzuzeigen, wenn ein Benutzer eine Taste drückt, um Daten in einem bestimmten Textfeld in CRM einzugeben. Sie können auch einen benutzerdefinierten Befehl mit einem Symbol am unteren Rand der Dropdownliste hinzufügen. Beim Auswählen eines Elements in der Dropdownliste wird der Wert im zum ausgewählten Elements geändert, die Dropdownliste wird ausgeblendet und das OnChange-Ereignis für das Textfeld wird aufgerufen.

Xrm.Page.getControl(arg).showAutoComplete(object)

  • Parameter
    Typ: Objekt, das die Ergebnismenge definiert, die results und commands enthält, die in der Dropdownliste der automatischen Vervollständigung angezeigt werden.

    Anmerkungen: Rufen Sie diese Methode in einer Funktion auf, die Sie mithilfe der addOnKeyPress-Methode verwenden, um das keypress-Ereignis auszuführen.

    Beispiel: Das folgende Beispiel zeigt die Definition das Objekts, das an die showAutoComplete-Methode übergeben werden soll.

    var resultset = { 
   results: [{ 
         id: <value1>, 
         icon: <url>, 
         fields: [<fieldValue1>]}, 

         {...}, 

         { 
         id: <valueN>, 
         icon: <url>, 
         fields: [<fieldValue1, fieldValue2,..., fieldValueN>]}],
   commands:{ 
         id: <value>, 
         icon: <url>, 
         label: <value>, 
         action: <function reference> 
   } 
}

hideAutoComplete

Verwenden Sie diese Funktion, um die Dropdownlisten für die automatische Vervollständigung auszublenden, die Sie für ein bestimmtes Textfeld konfiguriert haben.

Xrm.Page.getControl(arg).hideAutoComplete()

Hinweis

Sie müssen die hideAutoComplete-Methode nicht unbedingt verwenden, da die Dropdown-Liste standardgemäß automatisch versteckt wird, wenn der Benutzer wo anders klickt oder wenn eine neue Dropdown-Liste angezeigt wird. Diese Funktion ist verfügbar, wenn Entwickler die Dropdown-Liste zur automatischen Vervollständigung explizit verstecken muss, um ein benutzerdefiniertes Szenario zu handhaben.

Deaktiviert

Verwenden Sie getDisabled und setDisabled, um zu ermitteln, ob ein Steuerelement deaktiviert ist oder um es zu aktivieren oder zu deaktivieren.

Steuerelementtypen: standard, lookup, optionset.

getDisabled

Gibt zurück, ob das Steuerelement deaktiviert ist.

Xrm.Page.getControl(arg).getDisabled()
  • Rückgabewert
    Typ: Boolesch. "True", wenn das Steuerelement deaktiviert ist, andernfalls "false".

setDisabled

Festlegen, ob das Steuerelement deaktiviert ist.

Xrm.Page.getControl(arg).setDisabled(bool)
  • Argumente
    Typ: Boolesch. "True", wenn das Steuerelement deaktiviert werden soll, andernfalls "false".

getAttribute

Gibt das Attribut zurück, an das das Steuerelement gebunden ist.

Steuerelementtypen: standard, lookup, optionset.

Xrm.Page.getControl(arg).getAttribute()

Hinweis

Steuerelemente, die nicht an ein Attribut gebunden sind (Unterraster, Webressourcen und IFRAME) verwenden diese Methode nicht. Ein Fehler wird ausgelöst, wenn Sie versuchen, diese Methode für eines dieser Steuerelemente zu verwenden.

  • Rückgabewert
    Typ: Objekt: Ein Attribut.

Anmerkungen

Die zugehörigen Steuerelemente in einem Schnellansicht-Steuerelement sind in der Steuerelement-Sammlung enthalten und diese Steuerelemente verwenden die getAttribute-Methode. Allerdings ist das Attribut nicht Teil der Attributsammlung für die Entität. Während Sie den Wert für das Attribut mithilfe von getValue abrufen können und sogar mithilfe von setValue den Wert ändern können, werden Änderungen, die Sie vornehmen, nicht in der Entität gespeichert.

Der folgende Code zeigt die Verwendung des Werts des mobilephone-Kontaktattributs beim Anzeigen in einem Firmenentitätsformular mithilfe eines Schnellansicht-Steuerelements namens contactQuickForm. Dieser Code verbirgt das Steuerelement, wenn der Wert des Attributs null ist.

var quickViewMobilePhoneControl = Xrm.Page.getControl("contactQuickForm_contactQuickForm_contact_mobilephone");
 if (quickViewMobilePhoneControl.getAttribute().getValue() == null)
 {
  quickViewMobilePhoneControl.setVisible(false);
 }

getControlType

Gibt einen Wert zurück, der Steuerelemente kategorisiert.

Steuerelementtypen: Alle.

Xrm.Page.getControl(arg).getControlType()

  • Rückgabewert
    Typ: Zeichenfolge

    Mögliche Rückgabewerte von getControlType:

    Rückgabewert

    Beschreibung

    standard

    Ein Standardsteuerelement

    iframe

    Ein IFRAME-Steuerelement

    lookup

    Ein Suchsteuerelement.

    optionset

    Ein Optionssatz-Steuerelement

    subgrid

    Ein Unterraster-Steuerelement

    webresource

    Ein Webressourcen-Steuerelement

    notes

    Ein Hinweis-Steuerelement

    timercontrol

    Ein Zeitgeber-Steuerelement

    kbsearch

    Ein Suchsteuerelement für die Wissensdatenbank.

    customcontrol: <namespace>.<name>

    Ein benutzerdefiniertes Steuerlement für mobile Dynamics 365-Clients (Smartphones und Tablets).

    customsubgrid:<namespace>.<name>

    Ein benutzerdefiniertes Dataset-Steuerlement für mobile Dynamics 365-Clients (Smartphones und Tablets).

getName

Gibt den Namen zurück, der dem Steuerelement zugewiesen ist.

Hinweis

Der Name, der einem Steuerelement zugewiesen wird, wird nicht bestimmt, bis das Formular geladen ist. Änderungen am Formular ändern ggf. den Namen, der einem angegebenen Steuerelement zugewiesen ist.

Steuerelementtypen: Alle.

Xrm.Page.getControl(arg).getName()
  • Rückgabewert
    Typ: Zeichenfolge. Der Name des Steuerelements.

getParent

Gibt einen Verweis auf das Abschnittsobjekt zurück, das das Steuerelement enthält.

Steuerelementtypen: Alle.

Xrm.Page.getControl(arg).getParent()

getValue

Ruft den neuesten Wert in einem Steuerelement ab, wenn Benutzer Zeichen in ein bestimmtes Text- oder Zahlenfeld eingeben. Diese Methode hilft Ihnen dabei, interaktive Erfahrungen aufzubauen, indem Daten überprüft und Benutzer gewarnt werden, wenn sie Zeichen in ein Steuerelement eingeben.

Die getValue Methode ist anders als das Attribut getValue Methode aufgrund der Steuermethode holt die Werte aus dem Steuerelement wieder, wenn der Anwender im Steuerelement gegensätzlich zum Attribut getValue Methode, dass der Wert wieder geholt wird nachdem der Anwender das Feld speichert.

Hinweis

Diese Methode wird nicht für Dynamics 365 mobile Clients (Smartphones und Tablets) unterstützt und ist nur für Aktualisierte Entitäten verfügbar.

Einen JavaScript-Beispielcode, der die Methode getValue verwendet wird, um die Funktion der automatischen Vervollständigung zu konfigurieren, finden Sie unter Beispiel: Automatische Vervollständigung in Dynamics 365-Steuerelementen.

Xrm.Page.getControl(arg).getValue()
  • Rückgabewert
    Typ: Zeichenfolge. Der aktuelle Datenwert für ein Steuerelement.

Keypress-Methoden

Verwenden addOnKeyPress, removeOnKeyPress und fireOnKeyPress-Methoden, um ein unmittelbares Feedback bereitzustellen oder Aktionen als Benutzertypen in einem Steuerelement auszuführen. Diese Methoden ermöglichen es Ihnen, Datenüberprüfungen in einem Steuerelement auszuführen, sogar bevor der Benutzer den Wert in ein Formular eingibt (speichert).

Hinweis

Diese Methoden werden für Dynamics 365 mobile Clients (Smartphones und Tablets) nicht unterstützt und sind nur für Aktualisierte Entitäten verfügbar.

addOnKeyPress

Verwenden Sie diesen Typ, um eine Funktion als den Ereignishandler für ein Tastendruckereignis hinzuzufügen. Wenn eine Taste in einem bestimmten Text- oder Zahlenfeld in CRM gedrückt wird, wird die entsprechende Funktion aufgerufen.

Einen JavaScript-Beispielcode, der die Methode addOnKeyPress verwendet wird, um die Funktion der automatischen Vervollständigung zu konfigurieren, finden Sie unter Beispiel: Automatische Vervollständigung in Dynamics 365-Steuerelementen.

Xrm.Page.getControl(arg).addOnKeyPress([function reference])

  • Parameter
    Typ:-Funktionsverweis

    Anmerkungen: Die Funktion wird unten auf der Ereignishandlerpipeline hinzugefügt. Der Ausführungskontext wird automatisch als der erste Parameter festgelegt, der an den Ereignishandler übergeben wird, der diese Methode verwendet.Weitere Informationen:Ausführungskontext (clientseitige Referenz)

    Sie sollten einen Verweis auf eine benannte Funktion anstelle einer anonymen Funktion verwenden, wenn Sie später den Ereignishandler für das Feld entfernen möchten.

removeOnKeyPress

Verwenden Sie diesen Typ, um einen Ereignishandler für ein Text- oder Zahlenfeld in CRM zu entfernen, den Sie mithilfe von addOnKeyPress hinzugefügt hatten.

Xrm.Page.getControl(arg).removeOnKeyPress([function reference])

  • Parameter
    Typ:-Funktionsverweis

    Anmerkungen: Wenn eine anonyme Funktion mithilfe der addOnKeyPress-Methode festgelegt wurde, kann sie nicht mithilfe dieser Methode entfernt werden

fireOnKeyPress

Verwenden Sie diesen Typ, um einen Ereignishandler manuell auszulösen, den Sie für die Ausführung bei einem keypress-Ereignis in einem bestimmten Text- oder Zahlenfeld erstellt haben.

Xrm.Page.getControl(arg).fireOnKeyPress()

Methoden für Wissensdatenbank-Suchsteuerelemente

Diese Methoden sind nur für das Suchsteuerelement für die Wissensdatenbank verfügbar, die verfügbar ist, wenn die Dynamics 365-Organisation für die Funktion Wissensmanagement aktiviert ist. Informationen zu diesen Steuerelementen finden Sie unter Suchsteuerelement für die Wissensdatenbank (clientseitige Referenz).

Beschriftung

Abrufen oder Ändern der Beschriftung für ein Steuerelement mit den getLabel- und setLabel-Methoden.

Steuerelementtypen: Alle.

getLabel

Gibt die Beschriftung für das Steuerelement zurück.

Xrm.Page.getControl(arg).getLabel()
  • Rückgabewert
    Typ: Zeichenfolge. Die Beschriftung des Steuerelements.

setLabel

Legt die Beschriftung für das Steuerelement fest.

Xrm.Page.getControl(arg).setLabel(label)
  • Argumente
    Typ: Zeichenfolge. Die neue Beschriftung für das Steuerelement.

Suchsteuerelementmethoden und -ereignisse

Steuern Sie die Ergebnisse, die für einen Benutzer zur Auswahl angezeigt werden, wenn sie den Wert eines Suchsteuerelements festlegen, mithilfe der addCustomFilter, addCustomView, getDefaultView und setDefaultView-Methode. Das Lookup-Steuerelement macht auch den PreSearch-Ereignis verfügbar, sodass Sie Ereignishandler programmgesteuert mit deraddPreSearch und removePreSearch-Methode hinzufügen können.

Steuerelementtypen: lookup.

addCustomFilter

Verwenden Sie es zum Hinzufügen weiterer Filter zu den Ergebnissen, die in der Suche angezeigt werden. Jeder Filter wird mit zuvor hinzugefügten Filtern als "AND"-Bedingung kombiniert.

Xrm.Page.getControl(arg).addCustomFilter(filter, entityLogicaName)

  • Argumente

    • filterXml
      Typ: Zeichenfolge: Das anzuwendende fetchXml-Filterelement. Beispiel:

      <filter type="and">
 <condition attribute="address1_city" operator="eq" value="Redmond" />
</filter>

    • entityLogicalName
      Typ: Zeichenfolge: (Optional) Ist dies festlegt, gilt der Filter nur für diesen Entitätstypen. Andernfalls gilt dieser für alle zurückgesendeten Entitätstypen.

  • Anmerkungen
    Weitere Informationen:FetchXML schema.

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

    Diese Methode kann nur in einer Funktion in einem Ereignishandler für das Nachschlagesteuerungs-PreSearch-Ereignis verwendet werden.

    Das folgende Codebeispiel wird für die Suche des Verkaufschance-Formulars Firma (parentaccountid) bereitgestellt. Wenn die Sdk.setParentAccountIdFilter-Funktion im Onload-Formularereignishandler festgelegt ist, wird die Sdk.filterCustomAccounts-Funktion zum PreSearch-Ereignis für diese Suche hinzugefügt. Das Ergebnis ist, dass nur Firmen mit dem Kategorie (accountcategorycode)-Wert Bevorzugter Kunde (1) zurückgegeben werden.

    var Sdk = window.Sdk || {};

Sdk.filterCustomerAccounts = function () {
    //Only show accounts with the type 'Preferred Customer'
    var customerAccountFilter = "<filter type='and'><condition attribute='accountcategorycode' operator='eq' value='1'/></filter>";
    Xrm.Page.getControl("parentaccountid").addCustomFilter(customerAccountFilter, "account");
}
//set 'Sdk.setParentAccountIdFilter' in the Opportunity form onload event handler
Sdk.setParentAccountIdFilter = function () {
    Xrm.Page.getControl("parentaccountid").addPreSearch(Sdk.filterCustomerAccounts);
}

addCustomView

Fügt eine neue Ansicht für das Suchdialogfeld hinzu.

Xrm.Page.getControl(arg).addCustomView(viewId, entityName, viewDisplayName, fetchXml, layoutXml, isDefault)

  • Argumente

    • viewId
      Typ: Zeichenfolge: Die Zeichenfolgendarstellung einer GUID für eine Ansicht.

      Hinweis

      Dieser Wert wird nie gespeichert und muss nur unter den anderen verfügbaren Ansichten für die Suche eindeutig sein. Eine Zeichenfolge für eine nicht-gültige GUID funktioniert, beispielsweise „{00000000-0000-0000-0000-000000000001}“. Es wird empfohlen, dass Sie ein spezielles Tool (beispielsweise guidgen.exe) verwenden, um eine gültige GUID zu generieren. Das guidgen.exe-Tool ist im Windows SDKenthalten.

    • entityName
      Typ: Zeichenfolge: Der Name der Entität.

    • viewDisplayName
      Typ: Zeichenfolge: Der Name der Ansicht.

    • fetchXml
      Zeichenfolge: Die fetchXml-Abfrage für die Ansicht.

    • layoutXml
      Typ: Zeichenfolge: Das XML, das das Layout der Ansicht definiert.

    • Ist Standard
      Typ: Boolesch: Bestimmt, ob die Ansicht die Standardansicht sein soll.

  • Anmerkungen
    Diese Methode funktioniert nicht mit Besitzer-Suchen. Besitzer-Suchen werden verwendet, um Datensätze im Besitz des Benutzers zuzuweisen.

DefaultView

Sie können ermitteln, welche Ansicht die anzuzeigende Standardansicht ist, um Benutzern zu ermöglichen, Datensätze in einer Suche auszuwählen, und die Standardansicht ändern, mithilfe von getDefaultView und setDefaultView.

getDefaultView

Gibt den ID-Wert der Standard-Suchdialogfeldansicht zurück.

Xrm.Page.getControl(arg).getDefaultView()
  • Rückgabewert
    Typ: Zeichenfolge. Der ID-Wert der Standardansicht.

setDefaultView

Legt die Standardansicht für das Suchsteuerelementdialogfeld fest.

Xrm.Page.getControl(arg).setDefaultView(viewGuid)
  • Argumente
    Typ: Zeichenfolge. Die ID der Ansicht, die als Standardansicht festgelegt wird.

Beispiel: Diese setDefaultViewSample-Funktion legt die Standardansicht des account-Formulars für die Suche nach dem primären Kontakt zu der Ansicht Meine aktiven Kontakte fest.

function setDefaultViewSample() {
    Xrm.Page.getControl("primarycontactid").setDefaultView("{00000000-0000-0000-00AA-000010001003}");
}​

PreSearch-Ereignis

Sie können Ereignishandler für die Nachschlagesteuerungs-PreSearch-Ereignis mithilfe der addPreSearch- und removePreSearch-Methoden hinzufügen oder entfernen.

Verwenden Sie das PreSearch-Ereignis, um zu steuern, welche Ergebnisse für das Steuerelement mithilfe der aktuellen Formulardaten angezeigt werden, wenn der Benutzer startet, nach Datensätzen zu suchen.

Bei beiden Methoden wird Ausführungskontext (clientseitige Referenz) als erster Parameter übergeben.

addPreSearch

Verwenden Sie diese Methode, um Änderungen für Suchen basierend auf aktuellen Werten anzuwenden, wenn dem Benutzer Ergebnisse der Suche angezeigt werden.

Xrm.Page.getControl(arg).addPreSearch(handler)

Das Argument ist eine Funktion, die kurz vor Suche ausgeführt wird, um Ergebnisse für eine Suche bereitzustellen. Sie können diesen Handler verwenden, um eine der anderen Suchsteuerelementfunktionen aufzurufen und die in der Suche anzuzeigenden Ergebnisse zu optimieren.

removePreSearch

Verwenden Sie diese Methode, um Ereignishandlerfunktionen zu entfernen, die zuvor für das PreSearch-Ereignis festgelegt wurden.

Xrm.Page.getControl(arg).removePreSearch(handler)

Benachrichtigung

Verwenden Sie diese Methoden, um Benachrichtigungen für ein Steuerelement anzuzeigen und zu löschen.

setNotification

Zeigt eine Fehlermeldung für das Steuerelement an, um anzugeben, dass Daten ungültig sind. Wenn diese Methode verwendet wird, erscheint ein rotes „X“-Symbol neben dem Steuerelement. Bei mobilen Dynamics 365-Clients wird die Meldung angezeigt, indem Sie auf das Symbol tippen.

Xrm.Page.getControl(arg).setNotification(message,uniqueId)

Anmerkungen

Das Festlegen einer Fehlermeldung für ein Steuerelement blockiert das Speichern des Formulars.

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

Argumente

  • Meldung
    Typ: Zeichenfolge: Die anzuzeigende Meldung.

  • uniqueId
    Typ: Zeichenfolge: Die ID zum Löschen von nur dieser Meldung bei Verwendung von clearNotification. (Optional).

Rückgabewert

Typ: Boolesch: Gibt an, ob die Methode erfolgreich war.

addNotification

Zeigt eine Fehler- oder Empfehlungs- Benachrichtigung für ein Steuerelement an und Sie können Aktionen angeben, die basierend auf der Benachrichtung ausgeführt werden sollen. Wenn Sie einen Fehlertyp für eine Benachrichtigung angeben, wird ein rotes „X“-Symbol neben dem Steuerelement angezeigt. Wenn Sie einen Empfehlungstyp für eine Benachrichtigung angeben, wird ein „i“-Symbol neben dem Steuerelement angezeigt. Auf mobilen Dynamics 365-Clients wird die Benachrichtung angezeigt, wenn Sie auf die Schaltfläche tippen, und Sie können die konfigurierten Aktionen ausführen, indem Sie auf die Schaltfläche Übernehmen klicken oder die Meldung schließen.

Xrm.Page.getControl(arg).addNotification(object)

Anmerkungen

Das Festlegen einer Fehlerbenachrichtigung in einem Steuerelement blockiert das Speichern des Formulars, während das Festlegen eine Empfehlungsbenachrichtigung das Speichern des Formulars nicht blockiert.

Diese Funktion wurde in Update für Dynamics 365 (online und lokal), Dezember 2016 eingeführt und ist nur für Aktualisierte Entitäten verfügbar.

Argumente

Die Methode akzeptiert ein Objekt mit den folgenden Attribute:

Attribut

Datentyp

Erforderlich

Beschreibung

messages

Array

Ja

Die Meldung, die die Benachrichtigung anzeigt. In der aktuellen Version wird nur die erste Nachricht, die in diesem Array angegeben wird, angezeigt. Eine angegebene Zeichenfolge wird als fetter Text in der Benachrichtung angezeigt und wird in der Regel für Titel oder Betreff verwendet. Sie sollten Ihre Mitteilung auf 50 Zeichen beschränken, um eine optimale Benutzerfreundlichkeit zu gewährleisten.

notificationLevel

Zeichenfolge

Nein

Definiert den Typ der Benachrichtigung. Gültige Werte sind ERROR oder RECOMMENDATION. Wenn Sie dieses Attribut nicht in der Objektdefinition angeben, wird es standardmäßig auf ERROR festgelegt.

uniqueId

Zeichenfolge

Nein

Die ID, die genutzt wird, um diese Benachrichtigung zu löschen, wenn clearNotification verwendet wird.

actions

Array von Objekten

Nein

Eine Sammlung von Objekten mit den folgenden Attributen:

  • message: Zeichenfolge. Der sekundäre oder Benachrichtigungstext, der dem Benutzer angezeigt wird. Beschränken Sie Ihre Nachricht auf 100 Zeichen für eine optimale Benutzerfreundlichkeit.

  • actions: Array. Die entsprechenden Aktionen für die Nachricht.

In der aktuellen Version werden nur einzelne Mitteilungstexte und die entsprechende Aktion unterstützt. Allerdings können Sie mehrere Aufgaben definieren, um den JavaScript-Code in Aktionsblöcken auszuführen.

Hinweis

Die addNotification-Methode zeigt eine Benachrichtigung mit den Nachrichten, die Sie angegeben haben, an und zwei Standardschaltflächen: Übernehmen und Schließen. Wenn Sie auf Übernehmen klicken, wird die Aktion ausgeführt, die von Ihnen definiert wurde; klicken Sie auf Verwerfen wird die Benachrichtigung geschlossen.

Rückgabewert

Typ: Boolesch: Gibt an, ob die Methode erfolgreich war.

Beispiel

Der folgende Beispielcode zeigt eine Benachrichtigung im Feld Firmenname des Firmenformulars an, um das Tickersymbol festzulegen, wenn das Feld Firmenname "Microsoft" enthält. Wenn Sie auf Übernehmen in der Benachrichtigung klicken, wird das Tickersymbol-Feld auf "MSFT" festgelegt.

function addTickerSymbolRecommendation() {
    var myControl = Xrm.Page.getControl('name');
    var accountName = Xrm.Page.data.entity.attributes.get('name');
    var tickerSymbol = Xrm.Page.data.entity.attributes.get('tickersymbol');

    if (accountName.getValue('Microsoft') && tickerSymbol.getValue() != 'MSFT') {
        var actionCollection = {
            message: 'Set the Ticker Symbol to MSFT?',
            actions: null
        };

        actionCollection.actions = [function () {
            tickerSymbol.setValue('MSFT');
            myControl.clearNotification('my_unique_id');
        }];

        myControl.addNotification({
            messages: ['Set Ticker Symbol'],
            notificationLevel: 'RECOMMENDATION',
            uniqueId: 'my_unique_id',
            actions: [actionCollection]
        });
    }
    else
        console.log("Notification not set");
}

clearNotification

Entfernt eine Nachricht, die bereits für ein Steuerelement angezeigt wird.

Xrm.Page.getControl(arg).clearNotification(uniqueId)

Argumente

  • uniqueId
    Typ: Zeichenfolge: Die ID zum Löschen eines bestimmten Meldungssatzes, die bei Verwendung von setNotification oder addNotification eingerichtet wurde.

    Wenn der uniqueId-Parameter nicht festgelegt wird, wird die aktuelle angezeigte Benachrichtigung entfernt.

Anmerkungen

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

Rückgabewert

Typ: Boolesch: Gibt an, ob die Methode erfolgreich war.

OptionSet-Steuerelement-Methoden

Verwenden Sie die addOption-, clearOptions- und removeOption-Methoden, um die für OptionSet-Steuerelemente verfügbaren Optionen zu bearbeiten.

addOption

Fügt einem Optionssatzsteuerelement eine Option hinzu.

Xrm.Page.getControl(arg).addOption(option, [index])

Wichtig

Diese Methode überprüft nicht, ob die Werte in den Optionen, die Sie hinzufügen, gültig sind. Wenn Sie ungültige Optionen hinzufügen, funktionieren sie nicht ordnungsgemäß. Sie dürfen nur Optionen hinzufügen, die für das bestimmte Optionssatzattribut definiert wurden, an das das Steuerelement gebunden ist. Verwenden Sie die getOptions- oder getOption-Attributmethoden zum Abrufen gültiger Optionsobjekte, die mit dieser Methode hinzugefügt werden sollen.

  • Argumente

    • option
      Typ: Objekt: Ein Optionsobjekt, das zum OptionSet hinzugefügt wird.

    • index
      Typ: Anzahl: (Optional) Die Indexposition zum Platzieren der neuen Option in. Falls nicht verfügbar, wird die Option dem Ende hinzugefügt.

clearOptions

Löscht alle Optionen eines Optionssatzsteuerelements.

Xrm.Page.getControl(arg).clearOptions()

removeOption

Entfernt eine Option aus einem Optionssatzsteuerelement.

Xrm.Page.getControl(arg).removeOption(number)
  • Argumente
    Typ: Anzahl: Der Wert der Option, die Sie entfernen möchten.

setFocus

Legt den Fokus für das Steuerelement fest.

Xrm.Page.getControl(arg).setFocus()

ShowTime

Verwenden Sie setShowTime, um anzugeben, ob ein Datumssteuerelement den Zeitteil des Datums anzeigen sollte, und nutzen Sie getShowTime, um zu bestimmen, ob der Zeitteil des Datums aktuell angezeigt wird.

getShowTime

Dient zum Abrufen, ob ein Datumssteuerelement den Zeitteil des Datums anzeigt.

Steuerelementtypen: Standardsteuerelement für datetime-Attribute.

var showsTime = Xrm.Page.getControl(arg).getShowTime();

Anmerkungen

Diese Methode wurde mit Microsoft Dynamics CRM Online 2015-Update 1 eingeführt.

setShowTime

Geben Sie an, ob ein Datumssteuerelement den Zeitteil des Datums anzeigen soll.

Steuerelementtypen: Standardsteuerelement für datetime-Attribute.

Xrm.Page.getControl(arg).setShowTime(bool)

Anmerkungen

Diese Methode ist nur für Aktualisierte Entitäten verfügbar. Diese Methode zeigt oder verbirgt die Zeitkomponente eines Datumssteuerelements, wobei das Attribut das DateAndTime-Format verwendet. Diese Methode hat keine Auswirkungen, wenn das Format DateOnly verwendet wird.

Unterraster-Steuerelementmethoden

Für Versionen vor Microsoft Dynamics CRM Online 2015-Update 1 ist refresh die einzige Methode, die für ein Unterrastersteuerelement verfügbar ist. Bei CRM Online 2015-Update 1 gibt es neue Funktionen, die Sie verwenden können.Weitere Informationen:Rasterobjekte (schreibgeschützt)und -Methoden (clientseitige Referenz)

refresh

Aktualisiert die Daten, die in einem Unterraster angezeigt werden.

Xrm.Page.getControl(arg).refresh()

Hinweis

Die Aktualisierungsmethode ist im Formular OnLoad-Ereignis nicht verfügbar, weil Unterraster asynchron laden. Mit dem Unterraster OnLoad-Ereignis, das in CRM Online 2015-Update 1 eingeführt wurde, können Sie jetzt ermitteln, wann das Unterraster geladen wird, und diese Methode mit Ereignishandlern für dieses Ereignis verwenden.

Sichtbar

Legen Sie fest, welche Steuerelemente sichtbar sind und zeigen Sie sie an oder verbergen Sie sie, mithilfe der getVisible- und setVisible-Methoden.

getVisible

Gibt einen Wert zurück, der angibt, ob das Steuerelement derzeit angezeigt wird.

Hinweis

Wenn der beinhaltende Abschnitt oder die Registerkarte für dieses Steuerelement nicht angezeigt wird, kann diese Methode weiterhin true zurückgeben. So stellen Sie sicher, dass das Steuerelement tatsächlich angezeigt wird; Sie müssen auch die Sichtbarkeit der enthaltenden Elemente überprüfen.

Xrm.Page.getControl(arg).getVisible()
  • Rückgabewert
    Typ: Boolesch.True, wenn das Steuerelement sichtbar ist, andernfalls false.

setVisible

Legt einen Wert fest, der angibt, ob das Steuerelement angezeigt wird.

Xrm.Page.getControl(arg).setVisible(bool)
  • Argumente
    Typ: Boolesch.True, wenn das Steuerelement sichtbar werden soll, andernfalls false.

Hinweis

Wenn Sie den Benutzern selektiv Felder in Code anzeigen, der im Onload-Ereignis ausgeführt wird, ist es empfehlenswert, dass sie konfigurieren, dass die Felder standardmäßig nicht sichtbar sind und dann setVisible(true) verwenden, um die Felder anzuzeigen, wenn die Bedingungen stimmen. Das Verwenden von setVisible(false) zum Verbergen von Feldern im Onload-Ereignis kann dazu führen, dass das Feld dem Benutzer kurz angezeigt wird, bevor es ausgeblendet ist.

Wenn Sie eine größere Anzahl von Feldern mithilfe von setVisible(false) ausblenden, sollten Sie überlegen, ob Sie diese in Registerkarten oder Abschnitten gruppieren können und eher die Registerkarte oder den Abschnitt ausblenden anstelle der einzelnen Felder. Dies kann Leistung verbessern.

Webressourcen- und IFRAME-Steuerelementmethoden

Verwenden Sie diese Methoden, um mit Webressourcen- und IFRAME-Steuerelementen zu interagieren.

Daten

Webressourcen verfügen über einen speziellen Abfragezeichenfolgenparameter namens data zum Übergeben benutzerdefinierter Daten. Die getData- und setData-Methoden funktionieren nur für Silverlight-Webressourcen, die einem Formular hinzugefügt werden.Weitere Informationen:Übergeben von Daten aus einem Formular an eine eingebettete Silverlight-Webressource

Für Webressourcen einer Webseite (HTML) können die Datenparameter aus der getSrc-Methode extrahiert werden oder mit der setSrc-Methode festgelegt werden.

Hinweis

Die Methoden getData und setData werden für den interaktiven Servicehub nicht unterstützt.

getData

Gibt den Wert des Datenabfrage-Zeichenfolgenparameters zurück, der an eine Silverlight-Webressource übergeben wird.

Xrm.Page.getControl(arg).getData()
  • Rückgabewert
    Typ: Zeichenfolge. Der Datenwert, der an die Silverlight-Webressource übergeben wird.

setData

Legt den Wert des Datenabfrage-Zeichenfolgenparameters fest, der an eine Silverlight-Webressource übergeben wird.

Xrm.Page.getControl(arg).setData(string)
  • Argumente
    Typ: Zeichenfolge. Der Datenwert, der an die Silverlight-Webressource übergeben werden soll.

getInitialUrl

Gibt die Standard-URL zurück, für die ein IFRAME-Steuerelement so konfiguriert ist, sie anzuzeigen. Diese Methode ist nicht für Webressourcen verfügbar.

Xrm.Page.getControl(arg).getInitialUrl()
  • Rückgabewert
    Typ: Zeichenfolge. Die anfängliche URL.

getObject

Gibt das Objekt im Formular zurück, das ein I-Frame oder eine Webressource darstellt.

Xrm.Page.getControl(arg).getObject()

  • Rückgabewert
    Typ: Objekt. Bestimmt, welches Objekt vom Typ des Steuerelements abhängig ist.

    Ein IFRAME gibt das IFrame-Element vom Dokumentobjektmodell (DOM) zurück.

    Eine Silverlight-Webressource gibt das Object-Element vom DOM zurück, das das eingebettete Silverlight-Plug-In darstellt.

Src

IFRAMEs oder Webressourcen verfügen über eine src-Eigenschaft, um zu definieren, was im eingebetteten Fenster angezeigt werden soll. Sie können die src-Eigenschaft mithilfe der getSrc- und setSrc-Methoden abrufen oder ändern.

getSrc

Gibt die aktuelle URL zurück, die in einem IFRAME oder einer Webressource angezeigt wird.

Xrm.Page.getControl(arg).getSrc()
  • Rückgabewert
    Typ: Zeichenfolge. Eine URL, die die src-Eigenschaft des IFRAMEs oder der Webressource darstellt.

setSrc

Legt die URL fest, die in einem IFRAME oder einer Webressource angezeigt werden soll.

Xrm.Page.getControl(arg).setSrc(string)
  • Argumente
    Typ: Zeichenfolge: Die URL.

Siehe auch

Cclientseitige Programmierreferenz
Kurzübersicht zum Formularskripting
Xrm.Page.ui (clientseitige Referenz)
Schreiben von Code für Microsoft Dynamics 365-Formulare
Verwenden des Xrm.Page-Objektmodells

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright