Xrm.Page.data. 实体属性（客户端引用）

项目
10/31/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

属性包含窗体中的数据。使用 Xrm.Page.data.entity.属性集合或 Xrm.Page.getAttribute 快捷方法来访问属性集合。有关详细信息，请参阅集合（客户端引用）。

属性特性和方法

布尔和 OptionSet 属性方法
getInitialValue、getOption、getOptions、getSelectedOption 和 getText 提供了获取有关布尔或 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 方法来控制保存记录时属性的值是否会提交。
值
使用 getValuesetValue 方法来确定和改变属性的值。

布尔和 OptionSet 属性方法

getInitialValue、getOption、getOptions、getSelectedOption 和 getText 方法提供了获取有关 Boolean 或 OptionSet 属性信息的途径。

getInitialValue

当打开窗体时，返回表示 OptionSet 或 Boolean 属性值设置的值。

属性类型： Optionset 和布尔

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

返回值
类型： 数字。属性初始值。

getOption

返回带有传递到方法的参数匹配值的选项对象。

属性类型： 选项集

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

参数
字符串或数值
返回值
类型： 带有text 和 value 属性的选项对象。

getOptions

返回代表选项集属性有效选项的一组选项对象。

属性类型： 选项集

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

返回值
类型： 一组选项对象。

getSelectedOption

返回在选项集属性中所选的选项对象。

属性类型： 选项集

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

返回值
类型： 带有text 和 value 属性的选项对象。

getText

返回选项集属性当前所选选项文本的字符串值。

属性类型： 选项集

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.hideAllAttributeControls：显示属性的所有控件。

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	日期时间
整数	持续时间	integer	持续时间
单行文本	电子邮件	string	电子邮件
整数	语言	optionset	语言
整数	无	integer	无
单行文本	文本区域	string	文本区域
单行文本	文本	string	文本
单行文本	股票代号	string	tickersymbol
单行文本	电话	string	手机
整数	时区	optionset	时区
单行文本	URL	string	URL

getIsDirty

返回一个布尔值，指示属性值是否未保存更改。

属性类型： 所有

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

返回值
类型： 布尔。若未保存更改则为 True，否则为 False。

getIsPartyList

返回一个布尔值，指示查找是否表示 partylist 查找。 Partylist 查找允许设置多条记录，例如“To”：邮件实体记录字段

属性类型： 查找

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，以便使其在保存时不提交。若要强制提交无论其是否更改的属性值，请使用模式参数设置为“始终”的 setSubmitMode 函数。

在使用 setSubmitMode 时您有三个选项：

always：始终提交该值。
never：从不提交该值。设置此选项时，不能编辑属性窗体中的任何字段。
dirty（默认）：如果该值不为空，在创建时提交和仅在更改保存时提交。

使用 getSubmitMode 来确定当前设置。

getSubmitMode

返回一个字符串，指示属性数据在记录保存后提交。

属性类型： 所有

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

返回值
类型： 字符串

返回三个可能值之一：
- always
- never
- dirty
可编辑的字段的默认值为“错误”，这意味着只有当数据值更改时值会提交到服务器。

setSubmitMode

设置在保存记录时是否提交属性中的数据。

属性类型： 所有

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

参数
类型： 字符串

以下值之一
- always:在保存后，始终发送数据。
- never:已保存后，数据从不发送。在使用此时，不能编辑属性表单的字段。
- dirty:默认行为。更改保存时，发送数据。

值

在窗体脚本中，访问或设置值属性是通常执行的操作。

getValue

检索属性数据值。

属性类型： 所有

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

返回值
类型： 取决于属性类型。

属性类型	返回类型
布尔值	布尔值
日期时间	日期为获取使用 Microsoft Dynamics 365 用户区域首选项的数据的字符串版本，可使用格式和区域格式方法。设置日期的其他方法是使用操作系统区域设置，而不是用户的 Microsoft Dynamics 365 区域设置首选项。
十进制	号码
Double	号码
整数	号码
查找	Array 一组查找对象。备注某些查找允许设置与查找关联的多条记录，例如“To”：邮件实体记录字段。因此，所有的查找数据值使用一组查找对象—即使属性不支持添加多个记录引用。每个查阅具有以下属性： entityType 字符串：在查找中显示的实体名称 ID 字符串：查找中显示的记录的 GUID 值得字符串表示形式。名称字符串：查找中显示的代表记录的文本。
备忘录	字符串
货币	号码
选项集	号码
字符串	字符串

setValue

设置属性数据值。

属性类型： 所有

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

参数
类型取决于属性类型。

属性类型	参数类型
布尔值	布尔值
日期时间	日期
十进制	号码
双精度	号码
Integer	号码
查找	Array 一组查找对象。备注某些查找，称为为‘partylist’查找，允许设置与查找关联的多条记录，例如“To” ：邮件实体记录字段。因此，所有的查找数据值使用一组查找对象—即使属性不支持添加多个记录引用。每个查找值具有以下属性： entityType 字符串：查找代表的实体逻辑名称。 ID 字符串：查找中显示的记录的 GUID 值得字符串表示形式。值匹配以下格式：{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}。名称字符串：查找中显示的代表记录的文本。通常实体的主要属性。请参阅设置查找属性值帮助函数示例，以创建设置简单的查找属性值。
备忘录	字符串
货币	号码
选项集	号码备注 getOptions 方法返回选项值作为字符串。在使用这些值用于设置属性选项值前，必须使用 parseInt 将其转换为数字。有效 statuscode（状态描述）选项取决于记录的当前 statecode。不能在表单脚本里设置 statecode (状态)字段。若要了解哪些 statecode 值有效，请参阅属性的元数据。有关系统实体的默认值列表，请参阅 TechNet：默认状态和状态描述值。对于自定义实体可使用浏览组织的元数据描述的实体元数据浏览器。最后，还应考虑应用于字段的所有自定义状态转换。详细信息：TechNet：定义状态描述转换。
字符串	字符串备注带有电子邮件格式的字符串要求该字符串代表有效邮箱地址。

备注

使用 setValue 更新属性不会导致 OnChange 事件处理程序运行。如果希望 OnChange 事件处理程序运行，除了使用 setValue 之外，还必须使用 fireOnChange。
在适用于平板电脑的 Microsoft Dynamics 365 未连接到服务器时，setValue 不能工作。
无法设置复合属性的值。详细信息：为复合属性编写脚本。

设置查找属性值

以下示例演示 setSimpleLookupValue 帮助程序函数的定义，以设置简单查找属性的值。

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. 实体属性（客户端引用）

属性特性和方法

布尔和 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

设置查找属性值

另请参阅

其他资源