Xrm.Page.data.entity 屬性 (用戶端參考)

發行項
10/31/2017

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

屬性包含表單中的資料。使用 Xrm.Page.data.entity.fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_entityattributes 集合或 Xrm.Page.getAttribute 捷徑方法來存取屬性集合。如需詳細資訊，請參閱集合 (用戶端參考)。

屬性內容及方法

Boolean 和 OptionSet 屬性方法
getInitialValue、getOption、getOptions、getSelectedOption 和 getText 方法提供取得 Boolean 或 OptionSet 屬性相關資訊的方式。
控制項
與屬性相關聯的存取控制。
getAttributeType
取得屬性的類型。
getFormat
取得屬性格式。
getIsDirty
判斷自從上次儲存屬性之後，屬性值是否變更。
getIsPartyList
判斷查詢屬性是否代表 Partylist 查詢。
getMaxLength
取得儲存字串資料之屬性可擁有的最大字串長度。
getName
取得屬性的名稱。
getParent
取得身為所有屬性上層之 Xrm.Page.data.entity 物件的參考。
getUserPrivilege
判斷使用者對於使用欄位層級安全性之欄位所擁有的權限。
數值屬性方法
使用 getMax、getMin 和 getPrecision 方法來存取數值屬性內容的相關資訊。
OnChange 事件
使用 addOnChange、removeOnChange 和 fireOnChange 方法來管理 OnChange 事件的事件處理常式。
RequiredLevel
使用 setRequiredLevel 和 getRequiredLevel 方法來控制屬性是否必須具有值才能儲存記錄。
SubmitMode
使用 setSubmitMode 和 getSubmitMode 方法來控制是否要在儲存記錄時送出屬性的值。
值
使用 getValue 和 setValue 方法，判斷對屬性所設定的值以及將值變更。

Boolean 和 OptionSet 屬性方法

getInitialValue、getOption、getOptions、getSelectedOption 和 getText 方法提供取得 Boolean 或 OptionSet 屬性相關資訊的方式。

getInitialValue

傳回值，這個值代表在表單開啟時設定給 OptionSet 或 Boolean 的值。

屬性類型： Optionset 和 Boolean

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

傳回值
類型： 數值。屬性的初始值。

getOption

傳回選項物件，包含符合傳遞至方法之引數的值。

屬性類型： optionset

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

引數
字串值或數值。
傳回值
類型： 具有 text 和 value 屬性的選項物件。

getOptions

傳回選項物件的陣列，這些物件代表 optionset 屬性的有效選項。

屬性類型： optionset

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

傳回值
類型： 選項物件陣列。

getSelectedOption

傳回在 optionset 屬性中選取的選項物件。

屬性類型： optionset

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

傳回值
類型： 具有 text 和 value 屬性的選項物件。

getText

傳回 optionset 屬性目前所選取選項之文字的字串值。

屬性類型： optionset

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

傳回值
類型： 字串。所選取選項的 text 值。

注意

未選取任何選項時，getText 會傳回空字串值。

控制項

請參閱集合 (用戶端參考)，以了解集合所公開的方法。

因為每個屬性可能在頁面上呈現不只一次，控制項集合可讓您存取代表該屬性的所有控制項。如果屬性僅由頁面中的一個欄位代表，則此集合的長度將會是 1。當您使用控制項 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getName 方法時，第一個控制項的名稱將會與屬性名稱相同。該屬性的第二個控制項執行個體會是「<attributeName>1」。每個針對特定屬性新增至表單的額外控制項會繼續沿用模式 <attributeName>+N。

當表單在頁首中顯示商務程序流程控制項時，將會為商務程序流程中顯示的每個屬性新增額外的控制項。這些控制項會有類似下列的唯一名稱：header_process_<attribute name>。

對繫結至屬性的控制項執行動作時，您永遠都必須考慮控制項可能會加入頁面中不只一次，而您通常應該對屬性的每個控制項執行相同的動作。您可以在屬性控制集合執行迴圈，對每個控制項執行動作來這麼做。

下列範例表示具有兩個可重複使用之函數的 JavaScript 程式庫，而這些函數使用屬性控制集合來隱藏和顯示控制項：

SDK.Sample.hideAllAttributeControls：隱藏屬性的所有控制項。
SDK.Sample.showAllAttributeControls：顯示屬性的所有控制項。

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);
            }
        );
}

若要使用這些函數，請傳遞屬性的邏輯名稱，如下所示：

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

getAttributeType

傳回代表屬性類型的字串值。

屬性類型：所有

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

傳回值
類型： 字串

此方法會傳回下列其中一個字串值：
- boolean
- datetime
- decimal
- double
- integer
- lookup
- memo
- money
- optionset
- string

getFormat

傳回代表屬性的格式設定選項。

屬性類型：所有

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

傳回值
類型： 字串

此方法會傳回下列其中一個字串值或 null：
- date
- datetime
- duration
- email
- language
- none
- phone
- text
- textarea
- tickersymbol
- timezone
- url

注意

此格式資訊通常表示應用程式欄位的格式選項。未提供布林欄位的格式選項。

下表列出每個屬性結構描述類型及格式選項的格式字串預期值。

應用程式欄位類型	格式選項	屬性類型	格式值
日期及時間	只有日期	datetime	日期
日期及時間	日期及時間	datetime	datetime
整數	期間	integer	duration
單行文字	電子郵件	string	電子郵件
整數	語言	optionset	語言
整數	無	integer	無
單行文字	文字區域	string	文字區域
單行文字	文字	string	文字
單行文字	股票看板代號	string	跑馬燈符號
單行文字	電話	string	電話
整數	時區	optionset	時區
單行文字	URL	string	URL

getIsDirty

傳回布林值，這個值表示屬性值是否有未儲存的變更。

屬性類型：所有

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

傳回值
類型： 布林。如果有未儲存的變更則為 true，否則為 false。

getIsPartyList

傳回布林值，這個值表示查詢是否代表 Partylist 查詢。 Partylist 查詢允許設定多個記錄，例如實體記錄的 [收件者:] 欄位。

屬性類型： 查詢

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

傳回值
類型： 布林。如果查詢屬性是 Partylist 則為 true，否則為 false。
備註
此方法僅適用於41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

getMaxLength

傳回表示字串或備忘屬性最大長度的數字。

屬性類型： 字串、備忘

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

傳回值
類型： 數值。這個屬性允許的最大字串長度。

注意

電子郵件表單 description 屬性是備忘屬性，但是它沒有 getMaxLength 方法。

getName

傳回表示屬性邏輯名稱的字串。

屬性類型：所有

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

傳回值
類型： 字串。屬性的邏輯名稱。

getParent

傳回身為所有屬性上層的 Xrm.Page.data.entity 物件。

此函數是為了提供與其他物件的一致介面而存在。在此情況下，因為每個屬性都會傳回相同的物件，實際有用的場合不多。

屬性類型：所有

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

傳回值
類型：Xrm.Page.data.entity 物件。

getUserPrivilege

傳回包含三個布林屬性的物件，這些屬性對應於表示使用者是否可以建立、讀取或更新屬性資料值的權限。這個函數適合在欄位層級安全性修改使用者對特定屬性的權限時使用。如需詳細資訊，請參閱欄位安全性如何用於控制 Microsoft Dynamics 365 欄位值的存取。

屬性類型：所有

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

傳回值
類型： 物件

此物件有三個布林屬性：
- canRead
- canUpdate
- canCreate

數值屬性方法

使用 getMax、getMin 和 getPrecision 方法來存取數值屬性內容的相關資訊。

getMax

傳回表示屬性最大允許值的數值。

屬性類型： 金額、十進位、整數、雙精確度浮點數

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

傳回值
類型： 數值。屬性的最大允許值。

getMin

傳回表示屬性最小允許值的數值。

屬性類型： 金額、十進位、整數、雙精確度浮點數

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

傳回值
類型： 數值。屬性的最小允許值。

getPrecision

傳回小數點右邊允許的位數。

屬性類型： 金額、十進位、雙精確度浮點數和整數

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

傳回值
類型： 數值。小數點右邊允許的位數。

OnChange 事件

有三個方法可以用來處理屬性的 OnChange 事件：

addOnChange
removeOnChange
fireOnChange

addOnChange

設定要在屬性值變更時呼叫的函數。

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

參數
類型： 函數指標

備註： 這個函數會加入至事件處理常式管線底端。執行內容是自動設定為傳遞至事件處理常式的第一個參數。如需詳細資訊，請參閱執行內容 (用戶端參考)。

範例： 在此範例中，JScript 程式庫包含兩個函數。將 addMessageToOnChange 函數加入至表單 OnLoad 事件會新增 displayMessage 函數做為表單中第一個屬性 OnChange 事件的處理常式。
```
function addMessageToOnChange() 
{ 
   Xrm.Page.data.entity.attributes.get(0).addOnChange(displayOrgName);
}
function displayOrgName(execContext) 
{ 
   Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
}
```

removeOnChange

從屬性的 OnChange 事件處理常式移除函數。

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

參數
類型： 函數參考

範例： 在此範例中，JScript 程式庫包含兩個函數。將 removeMessageFromOnChange 函數加入至其他表單事件會刪除身為表單中第一個屬性 OnChange 事件處理常式的 displayOrgName 函數。
```
function removeMessageFromOnChange() 
{
   Xrm.Page.data.entity.attributes.get(0).removeOnChange(displayOrgName);
}
function displayOrgName(execContext) 
{ 
   Xrm.Utility.alertDialog(execContext.getContext().getOrgUniqueName()); 
}
```

fireOnChange

導致屬性發生 OnChange 事件，讓任何與該事件關聯的指令碼可以執行。

屬性類型：所有

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

RequiredLevel

您可以控制應用程式是否要求欄位必須先含有資料才能儲存記錄。使用 getRequiredLevel 和 setRequiredLevel 方法來調整此需求。

getRequiredLevel

傳回字串值，這個值表示屬性的值是必要項還是建議項。

屬性類型：所有

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

傳回值
類型： 字串

傳回三個可能值的其中一個：
- none
- required
- recommended

setRequiredLevel

設定屬性在儲存記錄前必須還是建議要有資料。

重要

在儲存頁面時減少屬性的必要層級可能導致錯誤。如果屬性是伺服器的必要項，當屬性沒有值時，將會發生錯誤。

僅限表單上的欄位支援此方法。您無法將此方法與商務程序控制項中顯示的屬性搭配用來設定商務程序流程步驟的需求等級。如需適用於商務程序流程步驟之用戶端方法的詳細資訊，請參閱步驟方法

屬性類型：所有

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

引數
類型： 字串

下列其中一個值：
- none
- required
- recommended

SubmitMode

您可以控制屬性在建立或儲存記錄時送出資料的時機。例如，表單上可能會有只是要控制表單中邏輯的欄位。您對擷取其中資料不感興趣。您可能進行設定，讓資料不會儲存。或者可能會註冊依存於永遠要納入之值的外掛程式。您可能需要設定屬性，讓該屬性永遠會併入。未在初次儲存記錄之後取得更新的屬性 (例如 createdby) 會被設定，讓這些屬性不會在儲存時送出。若要強制不論屬性是否已變更都要將其值送出，請使用模式參數設定為 "always" 的 setSubmitMode 函數。

使用 setSubmitMode 時，您有三個選項：

always：永遠會送出值。
never：永遠不會送出值。設定此選項時，無法對此屬性在表單中任何欄位的資料進行編輯。
dirty (預設)：建立時，若值不為 null 則送出，以及儲存時，值必須有所變更才會送出。

使用 getSubmitMode 來判斷目前的設定。

getSubmitMode

傳回字串，這個字串表示屬性在儲存記錄後送出資料的時機。

屬性類型：所有

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

傳回值
類型： 字串

傳回三個可能值的其中一個：
- always
- never
- dirty
可編輯欄位的預設值是 'dirty'，表示只有在資料值已變更時，才會將值送出至伺服器。

setSubmitMode

設定是否在儲存記錄時送出屬性的資料。

屬性類型：所有

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

引數
類型： 字串

下列其中一個值：
- always：永遠在儲存時傳送資料。
- never：永遠不會在儲存時傳送資料。使用這個值時，無法對此屬性在表單中的欄位進行編輯。
- dirty：預設行為。當資料有所變更並儲存時會傳送資料。

值

存取或設定屬性的值是表單指令碼最常執行的動作。

getValue

擷取屬性的資料值。

屬性類型：所有

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

傳回值
類型： 視屬性類型而定。

屬性類型	傳回類型
boolean	Boolean
datetime	日期若要使用 Microsoft Dynamics 365 使用者的地區設定偏好設定取得日期的字串版本，請使用 format 和 localeFormat 方法。其他方法將會使用作業系統地區設定，而非使用者的 Microsoft Dynamics 365 地區設定偏好設定來格式化日期。
十進位	數字
Double	數字
integer	數字
lookup	陣列查詢物件的陣列。注意某些查詢允許在查詢中建立與多個記錄的關聯，例如實體記錄的 [收件者:] 欄位。因此，所有的查詢資料值都會使用查詢物件陣列，即使查詢屬性不支援新增多個記錄參考。每個查詢都有下列屬性： entityType 字串：實體顯示在查詢中的名稱。識別碼字串：查詢中所顯示之記錄的 GUID 值字串表示。名稱字串：表示要顯示在查詢中的記錄的文字。
備忘	String
money	數字
optionset	數字
字串	String

setValue

設定屬性的資料值。

屬性類型：所有

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

引數
視屬性類型而定。

屬性類型	引數類型
boolean	Boolean
datetime	日期
十進位	數字
double	數字
整數	數字
lookup	陣列查詢物件的陣列。注意某些查詢 (稱為 partylist 查詢) 允許在查詢中建立與多個記錄的關聯，例如實體記錄的 [收件者:] 欄位。因此，所有的查詢資料值都會使用查詢物件陣列，即使查詢屬性不支援新增多個記錄參考。每個查詢值都有下列屬性： entityType 字串：查詢所代表之實體的邏輯名稱。識別碼字串：查詢中所顯示之記錄的 GUID 值字串表示。這個值應符合下列格式：{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}。名稱字串：表示要顯示在查詢中的記錄的文字。通常是實體的主要屬性。如需可建立用來設定簡單查詢屬性值的 Helper 函數範例，請參閱設定查詢屬性值。
備忘	String
money	數字
optionset	數字注意 getOptions 方法會以字串傳回選項值。您先必須使用 parseInt 將它們轉換成數值，才能使用這些值來設定 optionset 屬性的值。有效的 statuscode (狀態原因) 選項取決於記錄目前的狀態碼。statecode (狀態) 欄位無法在表單指令碼中設定。若要了解哪些 statecode 值有效，請參閱屬性的中繼資料。如需系統實體的預設值清單，請參閱TechNet：預設狀態與狀態原因值。如果是自訂實體，請使用瀏覽組織的中繼資料中所述的實體中繼資料瀏覽器。最後，也考量已套用至欄位的任何自訂狀態轉換。其他資訊：TechNet：定義狀態原因轉換。
字串	String 注意具有電子郵件格式的字串欄位必須使用表示有效電子郵件地址的字串。

注意

使用 setValue 更新屬性不會導致 OnChange 事件處理常式執行。如果您想要讓 OnChange 事件處理常式執行，除了 setValue 之外，您還必須使用 fireOnChange。
當平板電腦專用 Microsoft Dynamics 365 未連線至伺服器時，setValue 無法運作。
您無法設定複合屬性的值。其他資訊：為複合屬性撰寫指令碼。

設定查詢屬性值

下列範例顯示 setSimpleLookupValue Helper 函數的定義，這個函數會設定簡單查詢屬性的值。

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);
  }

以下是使用 setSimpleLookupValue 函數在客戶表單上設定 primarycontactid 屬性值的範例：

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

另請參閱

用戶端程式設計參考
 表單指令碼快速參考
 撰寫 Microsoft Dynamics 365 表單的程式碼
 使用 Xrm.Page 物件模型

Microsoft Dynamics 365

共用方式為

Xrm.Page.data.entity 屬性 (用戶端參考)

屬性內容及方法

Boolean 和 OptionSet 屬性方法

getInitialValue

getOption

getOptions

getSelectedOption

getText

控制項

getAttributeType

getFormat

getIsDirty

getIsPartyList

getMaxLength

getName

getParent

getUserPrivilege

數值屬性方法

getMax

getMin

getPrecision

OnChange 事件

addOnChange

removeOnChange

fireOnChange

RequiredLevel

getRequiredLevel

setRequiredLevel

SubmitMode

getSubmitMode

setSubmitMode

值

getValue

setValue

設定查詢屬性值

另請參閱

其他資源