Attributo Xrm.Page.data.entity (riferimento lato client)

 

Data di pubblicazione: novembre 2016

Si applica a: Dynamics CRM 2015

Gli attributi contengono i dati nel modulo. Utilizzare la raccolta Xrm.Page.data.entity.attributi o il metodo veloce Xrm.Page.getAttribute per accedere a una raccolta di attributi. Per ulteriori informazioni, vedere Raccolte (riferimento lato client).

Proprietà degli attributi e metodi

• Metodi degli attributi Boolean e OptionSet
  I metodi getInitialValue, getOption, getOptions, getSelectedOption e getText offrono modi per ottenere informazioni sugli attributi Boolean o OptionSet.

• controls
  Controlli di accesso associati agli attributi.

• getAttributeType
  Ottenere il tipo di attributo.

• getFormat
  Ottenere il formato dell'attributo.

• getIsDirty
  Stabilire se il valore di un attributo è cambiato dall'ultimo salvataggio.

• getIsPartyList
  Stabilire se un attributo di tipo lookup rappresenta una ricerca di tipo partylist.

• getMaxLength
  Ottenere la lunghezza massima di stringa che può avere un attributo che archivia dati di stringa.

• getName
  Ottenere il nome dell'attributo.

• getParent
  Ottenere un riferimento all'oggetto Xrm.Page.data.entity che è l'elemento padre di tutti gli attributi.

• getUserPrivilege
  Stabilire quali privilegi ha un utente per i campi con l'impostazione Sicurezza a livello di campo.

• Metodi dell'attributo di numero
  Utilizzare i metodi getMax, getMin e getPrecision per accedere alle informazioni sulle proprietà degli attributi di numero.

• Evento OnChange
  Utilizzare i metodi addOnChange, removeOnChange e fireOnChange per gestire i gestori eventi per l'evento OnChange.

• RequiredLevel
  Utilizzare i metodi setRequiredLevel e getRequiredLevel per verificare se un attributo deve avere un valore per poter salvare un record.

• SubmitMode
  Utilizzare i metodi setSubmitMode e getSubmitMode per verificare se il valore di un attributo viene inviato al salvataggio di un record.

• Valore
  Utilizzare i metodi getValue e setValue per determinare i valori impostati per un attributo e modificare il valore.

Metodi degli attributi Boolean e OptionSet

I metodi getInitialValue, getOption, getOptions, getSelectedOption e getText offrono modi per ottenere informazioni sugli attributi Boolean o OptionSet.

getInitialValue

Restituisce un valore che rappresenta il set di valori per un attributo OptionSet o Boolean all'apertura del modulo.

Tipi di attributo: OptionSet e Boolean

Xrm.Page.getAttribute(arg).getInitialValue()

• Valore restituito
  Tipo: numero. Valore iniziale per l'attributo.

getOption

Restituisce un oggetto opzione con il valore corrispondente all'argomento passato al metodo.

Tipi di attributi: OptionSet

Xrm.Page.getAttribute(arg).getOption(value)

• Argomenti
  Valore stringa o numero

• Valore restituito
  Tipo: oggetto opzione con proprietà text e value.

getOptions

Restituisce una matrice di oggetti opzione che rappresentano le opzioni valide per un attributo OptionSet.

Tipi di attributi: OptionSet

Xrm.Page.getAttribute(arg).getOptions()

• Valore restituito
  Tipo: matrice di oggetti opzione.

getSelectedOption

Restituisce l'oggetto opzione selezionato in un attributo OptionSet.

Tipi di attributi: OptionSet

Xrm.Page.getAttribute(arg).getSelectedOption()

• Valore restituito
  Tipo: oggetto opzione con proprietà text e value.

getText

Restituisce un valore stringa del testo per l'opzione selezionata attualmente per un attributo OptionSet.

Tipi di attributi: OptionSet

Xrm.Page.getAttribute(arg).getText()

• Valore restituito
  Tipo: stringa. Valore text dell'opzione selezionata.

  Nota

  Se non è selezionata alcuna opzione, getText restituirà un valore stringa vuoto.

controls

Vedere Raccolte (riferimento lato client) per informazioni sui metodi esposti dalle raccolte.

Poiché ogni attributo può essere rappresentato più di una volta nella pagina, la raccolta di controlli consente di accedere a tutti i controlli che rappresentano tale attributo. Se l'attributo è rappresentato da un solo campo nella pagina, la durata della raccolta sarà 1. Quando si utilizza il metodo di controllo getName il nome del controllo dallo stesso del nome dell'attributo. La seconda istanza di un controllo per tale attributo sarà '<attributeName>1'. Lo schema <attributeName>+N continuerà per ogni altro controllo aggiunto al modulo per un attributo specifico.

Se un modulo visualizza un controllo di processo aziendale nell'intestazione, verranno aggiunti controlli aggiuntivi per ogni attributo visualizzato nel processo aziendale. I controlli hanno un nome univoco come il seguente: header_process_<attribute name>.

Quando si eseguono azioni su controlli collegati a un attributo è sempre opportuno considerare che il controllo può essere incluso nella pagina più di una volta ed è in genere necessario eseguire le stesse azioni per ogni controllo per l'attributo. A tale scopo è possibile scorrere in ciclo la raccolta di controlli dell'attributo ed eseguire le azioni su ogni controllo.

Il seguente esempio rappresenta una libreria JavaScript con due funzioni riutilizzabili che utilizzano la raccolta di controlli dell'attributo per nascondere e visualizzare i controlli:

• SDK.Sample.hideAllAttributeControls: nasconde tutti i controlli per l'attributo.

• SDK.Sample.showAllAttributeControls: mostra tutti i controlli per l'attributo.

if (typeof (SDK) == "undefined")
{SDK = { __namespace: true }; }
SDK.Sample = { __namespace: true };
SDK.Sample.hideAllAttributeControls = function (attributeLogicalName) {
    /// <summary>
    /// Hides all controls for the attribute.
    /// </summary>
    /// <param name="attributeLogicalName" type="String" mayBeNull="false" optional="false" >
    /// The logical name of an attribute.
    /// </param>
    if ((typeof attributeLogicalName != "string") ||
        (attributeLogicalName.length <= 3))
    { throw new Error("SDK.Sample.hideAllAttributeControls attributeLogicalName parameter must be a string at least 4 characters long."); }
    Xrm.Page.getAttribute(attributeLogicalName).controls.forEach(
        function (control, i) {
            control.setVisible(false);
            }
        );
}
SDK.Sample.showAllAttributeControls = function (attributeLogicalName) {
    /// <summary>
    /// Shows all controls for the attribute.
    /// </summary>
    /// <param name="attributeLogicalName" type="String" mayBeNull="false" optional="false" >
    /// The logical name of an attribute.
    /// </param>
    if ((typeof attributeLogicalName != "string") ||
        (attributeLogicalName.length <= 3))
    { throw new Error("SDK.Sample.showAllAttributeControls attributeLogicalName parameter must be a string at least 4 characters long."); }
    Xrm.Page.getAttribute(attributeLogicalName).controls.forEach(
        function (control, i) {
            control.setVisible(true);
            }
        );
}

Per utilizzare queste funzioni, passare il nome logico dell'attributo come illustrato di seguito:

//Hide the controls for the subject attribute.
SDK.Sample.hideAllAttributeControls("subject");
//Show the controls for the subject attribute.
SDK.Sample.showAllAttributeControls("subject");

getAttributeType

Restituisce un valore stringa che rappresenta il tipo di attributo.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getAttributeType()

• Valore restituito
  Tipo: stringa.

  Questo metodo restituirà uno dei valori stringa seguenti:

  • boolean

  • datetime

  • decimal

  • double

  • integer

  • lookup

  • memo

  • money

  • optionset

  • string

getFormat

Restituisce un valore stringa che rappresenta le opzioni di formattazione per l'attributo.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getFormat()

• Valore restituito
  Tipo: stringa.

  Questo metodo restituirà uno dei valori stringa seguenti o null:

  • date

  • datetime

  • duration

  • email

  • language

  • none

  • phone

  • text

  • textarea

  • tickersymbol

  • timezone

  • url

Nella tabella seguente sono elencati i valori stringa di formattazione previsti per ogni tipo di attributo, tipo di schema e opzione di formattazione.

Tipo di campo applicazione	Opzione di formattazione	Tipo di attributo	Valore formato
Data e ora	Solo data	datetime	data
Data e ora	Data e ora	datetime	datetime
Numero intero	Durata	integer	durata
Una riga di testo	Posta elettronica	string	E-mail
Numero intero	Linguaggio	optionset	language
Numero intero	Nessuno	integer	Nessuno
Una riga di testo	Area testo	string	textarea
Una riga di testo	Testo	string	testo
Una riga di testo	Simbolo del titolo	string	tickersymbol
Una riga di testo	Telefono	string	telefono
Numero intero	Fuso orario	optionset	timezone
Una riga di testo	URL	string	URL

getIsDirty

Restituisce un valore booleano che indica se sono presenti modifiche non salvate del valore dell'attributo.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getIsDirty()

• Valore restituito
  Tipo: booleano. True in caso di modifiche non salvate, altrimenti false.

getIsPartyList

Restituisce un valore booleano che indica se la ricerca rappresenta una ricerca di tipo partylist. Le ricerche di tipo partylist consentono l'impostazione di più record, ad esempio il campo A: per un record dell'entità di posta elettronica.

Tipi di attributo: lookup

Xrm.Page.getAttribute(arg).getIsPartyList()

• Valore restituito
  Tipo: booleano. True se l'attributo di ricerca è partylist, altrimenti false.

• Note
  Questo metodo è disponibile solo per Entità aggiornate.

getMaxLength

Restituisce un numero che indica la lunghezza massima di un attributo memo o stringa.

Tipi di attributi: stringa, memo

Xrm.Page.getAttribute(arg).getMaxLength()

• Valore restituito
  Tipo: numero. Lunghezza massima concessa per una stringa per questo attributo.

  Nota

  L'attributo description del modulo di posta elettronica è un attributo memo, ma non dispone di un metodo getMaxLength.

getName

Restituisce stringa che rappresenta il nome logico dell'attributo.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getName()

• Valore restituito
  Tipo: stringa. Nome logico dell'attributo.

getParent

Restituisce l'oggetto Xrm.Page.data.entity che è l'elemento padre di tutti gli attributi.

Questa funzione ha lo scopo di fornire un'interfaccia coerente con altri oggetti. In questo caso, poiché ogni attributo restituisce lo stesso oggetto, non è utile in molte situazioni.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getParent()

• Valore restituito
  Tipo: oggetto Xrm.Page.data.entity.

getUserPrivilege

Restituisce un oggetto con tre proprietà booleane che corrispondono ai privilegi che indicano se l'utente può creare, leggere o aggiornare i valori dei dati per un attributo. Questa funzione è progettata per l'utilizzo quando Sicurezza a livello di campo modifica i privilegi di un utente per un determinato attributo. Per ulteriori informazioni, vedere Come usare la sicurezza dei campi per controllare l'accesso ai valori dei campi in Microsoft Dynamics CRM 2015.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getUserPrivilege()

• Valore restituito
  Tipo: oggetto.

  L'oggetto ha tre proprietà booleane:

  • canRead

  • canUpdate

  • canCreate

Metodi dell'attributo di numero

Utilizzare i metodi getMax, getMin e getPrecision per accedere alle informazioni sulle proprietà degli attributi di numero.

getMax

Restituisce un numero che indica il valore massimo consentito per un attributo.

Tipi di attributi: money, decimal, integer, double

Xrm.Page.getAttribute(arg).getMax()

• Valore restituito
  Tipo: numero. Valore massimo consentito per l'attributo.

getMin

Restituisce un numero che indica il valore minimo consentito per un attributo.

Tipi di attributi: money, decimal, integer, double

Xrm.Page.getAttribute(arg).getMin()

• Valore restituito
  Tipo: numero. Valore minimo consentito per l'attributo.

getPrecision

Restituisce il numero di cifre consentite a destra del separatore decimale.

Tipi di attributi: money, decimal, double e integer

Xrm.Page.getAttribute(arg).getPrecision()

• Valore restituito
  Tipo: numero. Numero di cifre consentite a destra del separatore decimale.

Evento OnChange

Esistono tre metodi che è possibile utilizzare per utilizzare l'evento OnChange per un attributo:

• addOnChange

• removeOnChange

• fireOnChange

addOnChange

Imposta una funzione da chiamare quando viene modificato il valore dell'attributo.

Xrm.Page.getAttribute(arg).addOnChange([function reference])

• Parametro
  Tipo: puntatore a funzione.

  Note: la funzione sarà aggiunta al fondo della pipeline del gestore eventi. Il contesto di esecuzione viene impostato automaticamente come primo parametro passato al gestore eventi. Per ulteriori informazioni, vedere Contesto di esecuzione (riferimento sul lato client).

  **Esempio:**in questo esempio, la libreria JScript contiene due funzioni. Se si aggiunge la funzione addMessageToOnChange all'evento OnLoad del modulo viene aggiunta la funzione displayMessage come gestore per l'evento OnChange per il primo attributo nel modulo.

  function addMessageToOnChange() 
  { 
     Xrm.Page.data.entity.attributes.get(0).addOnChange(displayOrgName);
  }
  function displayOrgName(execContext) 
  { 
     Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
  }
  

removeOnChange

Rimuove una funzione dal gestore dell'evento OnChange per un attributo.

Xrm.Page.getAttribute(arg).removeOnChange([function reference])

• Parametro
  Tipo: riferimento a funzione.

  Esempio: in questo esempio, la libreria JScript contiene due funzioni. Se si aggiunge la funzione removeMessageFromOnChange a un altro evento del modulo viene rimossa la funzione displayOrgName come gestore per l'evento OnChange per il primo attributo nel modulo.

  function removeMessageFromOnChange() 
  {
     Xrm.Page.data.entity.attributes.get(0).removeOnChange(displayOrgName);
  }
  function displayOrgName(execContext) 
  { 
     Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
  }
  

fireOnChange

Causa il verificarsi dell'evento OnChange sull'attributo per consentire l'esecuzione di qualsiasi script associato all'evento.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).fireOnChange()

RequiredLevel

È possibile controllare se l'applicazione richiederà che un campo contenga dati prima di poter salvare un record. Utilizzare i metodi setRequiredLevel e getRequiredLevel per modificare questo requisito.

getRequiredLevel

Restituisce un valore stringa che indica se un valore dell'attributo è obbligatorio o consigliato.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getRequiredLevel()

• Valore restituito
  Tipo: stringa.

  Torna uno di tre valori possibili:

  • none

  • required

  • recommended

setRequiredLevel

Imposta se i dati sono obbligatori o consigliati per l'attributo prima di poter salvare il record.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).setRequiredLevel(requirementLevel)

• Argomenti
  Tipo: stringa.

  Uno dei valori seguenti:

  • none

  • required

  • recommended

SubmitMode

È possibile controllare quando vengono inviati i dati per un attributo alla creazione o al salvataggio di un record. Ad esempio, è possibile che nel modulo sia presente un campo che ha il solo scopo di controllare la logica nel modulo. Non è necessario acquisire dati in tale campo. È possibile impostarlo in modo che i dati non vengano salvati. In alternativa, può essere presente un plug-in registrato che dipende dal fatto che sia sempre incluso il valore Si può impostare l'attributo in modo che venga sempre incluso. Gli attributi che non vengono aggiornati dopo il salvataggio iniziale del record, ad esempio createdby, vengono impostati in modo che non vengano inviati al salvataggio. Per imporre l'invio di un valore dell'attributo indipendentemente che sia cambiato o meno, utilizzare la funzione setSubmitMode con il parametro della modalità impostato su "sempre".

Quando si utilizza setSubmitMode sono disponibili tre opzioni:

• always: il valore viene sempre inviato.

• never: il valore non viene mai inviato. Se questa opzione viene impostata, i dati non possono essere modificati per qualsiasi campo nel modulo per questo attributo.

• dirty (impostazione predefinita): il valore viene inviato alla creazione se non è null e al salvataggio solo quando viene modificato.

Utilizzare getSubmitMode per determinare l'impostazione corrente.

getSubmitMode

Restituisce una stringa che indica quando verranno inviati i dati dell'attributo al salvataggio del record.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getSubmitMode()

• Valore restituito
  Tipo: stringa.

  Torna uno di tre valori possibili:

  • always

  • never

  • dirty

  Il valore predefinito per i campi modificabili è "dirty", pertanto il valore verrà inviato al server solo quando il valore dei dati viene modificato.

setSubmitMode

Stabilisce se i dati dell'attributo verranno inviati al salvataggio del record.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).setSubmitMode()

• Argomenti
  Tipo: stringa.

  Uno dei valori seguenti:

  • always: i dati vengono inviati sempre al salvataggio.

  • never: i dati non vengono inviati mai al salvataggio. Se questa opzione viene utilizzata, non è possibile modificare i campi del modulo per questo attributo.

  • dirty: comportamento predefinito. I dati vengono inviati al salvataggio se sono stati modificati.

Valore

L'accesso o l'impostazione del valore di attributi sono le azioni eseguite più comunemente negli script dei moduli.

getValue

Recupera il valore dei dati per un attributo.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).getValue()

• Valore restituito
  Tipo: dipende dal tipo di attributo.

  Tipo di attributo	Tipo restituito
  boolean	Booleano
  datetime	Data Per ottenere la versione della stringa di una data tramite le preferenze delle impostazioni locali di un utente di Microsoft Dynamics 365, utilizzare i metodi format e localeFormat. Altri metodi formatteranno le date utilizzando le impostazioni locali del sistema operativo anziché le preferenze delle impostazioni locali di Microsoft Dynamics 365 dell'utente.
  decimal	Numero
  Double	Numero
  integer	Numero
  lookup	Matrice Matrice di oggetti di ricerca. Nota Alcune ricerche consentono l'associazione di più record in una ricerca, ad esempio il campo A: per un record dell'entità di posta elettronica. Pertanto, tutti i valori dei dati di ricerca utilizzano una matrice di oggetti di ricerca, anche quando l'attributo di ricerca non supporta l'aggiunta di più di un riferimento di record. Ogni ricerca ha le proprietà seguenti: entityType Stringa: nome dell'entità visualizzato nella ricerca ID Stringa: rappresentazione di stringa del valore GUID per il record visualizzato nella ricerca. Nome Stringa: testo che rappresenta il record da visualizzare nella ricerca.
  memo	Stringa
  money	Numero
  optionset	Numero
  string	Stringa

setValue

Imposta il valore dei dati per un attributo.

Tipi di attributo: tutti

Xrm.Page.getAttribute(arg).setValue()

• Argomenti
  Dipende dal tipo di attributo.

  Tipo di attributo	Tipo di argomento
  boolean	Booleano
  datetime	Data
  decimal	Numero
  double	Numero
  Integer	Numero
  lookup	Matrice Matrice di oggetti di ricerca. Nota Alcune ricerche, note come ricerche di tipo "partylist", consentono l'associazione di più record in una ricerca, ad esempio il campo A: per un record dell'entità di posta elettronica. Pertanto, tutti i valori dei dati di ricerca utilizzano una matrice di oggetti di ricerca, anche quando l'attributo di ricerca non supporta l'aggiunta di più di un riferimento di record. Ogni valore di ricerca ha le proprietà seguenti: entityType Stringa: nome logico dell'entità rappresentata dalla ricerca. ID Stringa: rappresentazione di stringa del valore GUID per il record visualizzato nella ricerca. Il valore deve corrispondere al formato seguente: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}. Nome Stringa: testo che rappresenta il record da visualizzare nella ricerca. In genere, attributo primario per l'entità. Vedere Impostare il valore dell'attributo di tipo lookup per un esempio di funzione di supporto che è possibile creare per impostare valori semplici dell'attributo di tipo lookup.
  memo	Stringa
  money	Numero
  optionset	Numero Nota Il metodo getOptions restituisce i valori di opzione come stringhe. È necessario utilizzare parseInt per convertirle in numeri prima di poter utilizzare i valori per impostare il valore di un attributo optionset. Le opzioni statuscode (motivo stato) valide dipendono dall'attuale codice di stato del record. Il campo statecode (stato) non può essere impostato negli script dei moduli. Per individuare i valori statecode validi, vedere i metadati per gli attributi. Vedere TechNet: Valori predefiniti di stato e motivo stato per un elenco di valori predefiniti per le entità di sistema. Per le entità personalizzate utilizzare il browser dei metadati dell'entità descritto in Visualizzazione dei metadati per l'organizzazione. Infine, considerare anche eventuali transizioni di stato personalizzate che sono state applicate al campo.Ulteriori informazioni:TechNet: Definire transizioni di motivi stato.
  String	Stringa Nota Un campo di tipo stringa con formato di posta elettronica richiede che la stringa rappresenti un indirizzo di posta elettronica valido.

Impostare il valore dell'attributo di tipo lookup

Il seguente esempio illustra la definizione di una funzione di supporto setSimpleLookupValue che imposta il valore per semplici attributi di tipo lookup.

function setSimpleLookupValue(LookupId, Type, Id, Name) {
   /// <summary>
   /// Sets the value for lookup attributes that accept only a single entity reference.
   /// Use of this function to set lookups that allow for multiple references, 
   /// a.k.a 'partylist' lookups, will remove any other existing references and 
   /// replace it with just the single reference specified.
   /// </summary>
   /// <param name="LookupId" type="String" mayBeNull="false" optional="false" >
   /// The lookup attribute logical name
   /// </param>
   /// <param name="Type" type="String" mayBeNull="false" optional="false" >
   /// The logical name of the entity being set.
   /// </param>
   /// <param name="Id" type="String" mayBeNull="false" optional="false" >
   /// A string representation of the GUID value for the record being set.
   /// The expected format is "{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}".
   /// </param>
   /// <param name="Name" type="String" mayBeNull="false" optional="false" >
   /// The text to be displayed in the lookup.
   /// </param>
   var lookupReference = [];
   lookupReference[0] = {};
   lookupReference[0].id = Id;
   lookupReference[0].entityType = Type;
   lookupReference[0].name = Name;
   Xrm.Page.getAttribute(LookupId).setValue(lookupReference);
  }

Di seguito viene fornito un esempio in cui si utilizza la funzione setSimpleLookupValue per impostare il valore dell'attributo primarycontactid in un modulo di account:

setSimpleLookupValue("primarycontactid", "contact", "{6D9D4FCF-F4D3-E011-9D26-00155DBA3819}", "Brian Lamee");

Vedere anche

Riferimento programmazione sul lato client
Riferimento rapido dello scripting dei moduli
Creare il codice per moduli di Microsoft Dynamics CRM 2015
Utilizzare il modello a oggetti Xrm.Page

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright