Xrm.Page.ui 控制方法（客户端引用）

项目
07/06/2017

发布日期： 2016年11月

适用于： Dynamics CRM 2015

control 对象提供更改控件的演示或行为并确定相应属性的方法。

请使用以下集合访问控件：Xrm.Page.ui.控件、Xrm.Page.ui Section.控件或 Xrm.Page.data.entity Attribute.控件。Xrm.Page.getControl 方法是访问 Xrm.Page.ui.controls.get 的快捷方法。

本主题中的语法示例演示了如何使用 Xrm.Page.getControl 方法访问控件。依赖于传递到该方法的参数的那些控件。访问单一控件的 args 参数必须是控件或索引的名称。

当窗体在页眉中显示业务流程控件时，将为业务流程中显示的每个属性添加其他控件。这些控件具有唯一名称，例如 header_process_<attribute name>。

备注

仅业务流程活动阶段中的控件可按名称访问。

窗体页眉中显示的控件是可访问的并使用唯一名称，例如：header_<attribute name>。

对于绑定到属性的控件，通过 Xrm.Page.data.entity Attribute.控件集访问控件很常见。

控件属性和方法

已禁用
使用 getDisabled 和 setDisabled 方法，检测状态并启用或禁用控件。
getAttribute
获取绑定到控件的属性。
getControlType
获取有关控件类型的信息。
getName
获取控件的名称
getParent
获取控件所属的部分对象。
知识库控件方法
这些方法只能在 Microsoft Dynamics CRM Online 组织与 Parature 集成时，用于可用的知识库搜索控件。这些方法通过 Microsoft Dynamics CRM Online 2015 更新 1 引入。

有关这些控件的信息，请参阅 Parature 知识库搜索控件（客户端引用）。
标签
使用 getLabel 和 setLabel 方法获取或更改控件的标签。
Lookup 控件方法和事件
当用户使用 addCustomFilter、addCustomView、getDefaultView、setDefaultView 方法设置查找控件的值时，值会控制用户从中选择的显示结果。

使用 addPreSearch 和 removePreSearch 方法，您可以添加或移除 PreSearch 事件中的事件处理程序。
通知
使用 setNotification 和 clearNotification 方法，向用户显示和删除有关控件的通知。
OptionSet 控件方法
使用 addOption、clearOptions 和 removeOption 方法，修改显示在 OptionSet 控件中的选项。
ShowTime
使用 setShowTime 指定日期控件是否应显示日期和 getShowTime 的时间部分，以确定日期的时间部分当前是否显示。
Subgrid 控件方法
对于使用 CRM Online 2015 更新 1 的组织，有新的使用子网格控件的功能。详细信息：网格对象和方法（客户端引用）

对于其他组织，refresh 方法是可用于子网格控件的唯一方法。此方法将刷新子网格中显示的数据。
可见
确定哪些控件是可见的，然后使用 getVisible 和 setVisible 方法显示或隐藏该控件。
Web 资源和 IFRAME 控件方法
使用 getData、setData、getInitialUrl、getObject、setSrc 和 getSrc 方法，与 Web 资源和 IFRAME 控件交互。

已禁用

使用 getDisabled 和 setDisabled 检测是否禁用控件以启用或禁用此方法。

控件类型： 标准、查找、选项集。

getDisabled

返回决定控件是否被禁用的值。

Xrm.Page.getControl(arg).getDisabled()

返回值
类型： 布尔。如果控件已禁用，则返回 true，否则返回 false。

setDisabled

设置控件是否被禁用。

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

参数
类型： 布尔。如果控件应该被禁用，则返回 ture，否则返回 false。

getAttribute

返回绑定到控件的属性。

控件类型： 标准、查找、选项集。

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

备注

未绑定到属性（子网格、web 资源和 IFRAME）的控件没有此方法。如果尝试在其中一个控件中使用这一方法，将引发错误。

返回值
类型： 对象：一个属性。

备注

在快速视图控件中的构成控件被包含在控件集合中，且这些控件具有 getAttribute 方法。但是，属性不是实体的属性集的一部分。当您使用 getValue 检索属性的值时，甚至使用 setValue 更改值时，将不保存您所做的更改和实体。

使用一个名为 contactQuickForm 的快速视图控件在客户实体窗体上显示联系人 mobilephone 属性时，以下代码会显示此属性的值。当此属性的值为 null 时，此代码隐藏控件。

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

getControlType

返回分类控件的值。

控件类型： 全部。

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

返回值
类型： 字符串

可能返回的 getControlType 值：

返回值	说明
standard	一个标准控件。
iframe	一个 IFrame 控件
lookup	一个查找控件。
optionset	一个选项集控件。
subgrid	一个子网格控件。
webresource	一个 web 资源控件。
notes	一个注释控件
timercontrol	一个计时器控件。
kbsearch	知识库搜索控件。

getName

返回已分配给控件的名称。

备注

分配给控件的名称在窗体加载完成后才能确定。窗体的更改可能更改分配给特定控件的名称。

控件类型： 全部。

Xrm.Page.getControl(arg).getName()

返回值
类型： 字符串。控件的名称。

getParent

返回对包含控件的部分对象的引用。

控件类型： 全部。

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

返回值
类型： Xrm.Page.ui 部分（客户端引用）对象。

知识库控件方法

这些方法只能在 Microsoft Dynamics CRM Online 组织与 Parature 集成时，用于可用的知识库搜索控件。这些方法通过 Microsoft Dynamics CRM Online 2015 更新 1 引入。

有关这些控件的信息，请参阅 Parature 知识库搜索控件（客户端引用）。

getLabel

返回控件的标签。

Xrm.Page.getControl(arg).getLabel()

返回值
类型： 字符串。控件的标签。

setLabel

设置控件的标签。

Xrm.Page.getControl(arg).setLabel(label)

参数
类型： 字符串。控件的新标签。

Lookup 控件方法和事件

当用户使用 addCustomFilter、addCustomView、getDefaultView 和 setDefaultView 方法设置查找控件的值时，控制用户从中选择的显示结果。Lookup 控件还公开 PreSearch 事件，以便您能够使用 addPreSearch 和 removePreSearch 方法以编程方式添加事件处理程序。

控件类型： 查找。

addCustomFilter

用于将筛选器添加到查找控件中显示的结果。每个筛选器将作为“AND”条件与任何以前添加的筛选器合并。

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

参数
- filterXml
  类型： 字符串：要应用的 fetchXml 筛选器元素。例如：
```
<filter type="and">
 <condition attribute="address1_city" operator="eq" value="Redmond" />
</filter>
```
- entityLogicalName
  类型： 字符串：（可选）如果设置为此类型，则筛选器仅应用于该实体类型。否则，将应用于所有返回的实体类型。

备注
详细信息：FetchXML schema。

本方法仅用于更新的实体。

此方法只能用在对查找控件 PreSearch 事件的事件处理程序的某个函数。

以下代码示例适用于商机窗体“客户”(parentaccountid) 查找。当在 Onload 事件处理程序窗体中设置 Sdk.setParentAccountIdFilter 函数时，Sdk.filterCustomAccounts 函数被添加到 PreSearch 事件以进行查找。结果是只有具有“类别” (accountcategorycode) 值的“首选客户”(1)才能返回。

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

为查找对话框添加新视图。

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

参数
- 视图 ID
  类型： 字符串：表示要查看的 GUID 的字符串。
  
  备注
  
  从未保存该值并且仅在查找其他可用视图中该值需要是唯一的。无效的 GUID 的字符串即有效，例如“{00000000-0000-0000-0000-000000000001}”。建议您使用 guidgen.exe 等工具以生成有效的 GUID。guidgen.exe 工具被包括在 Windows SDK 中。
- entityName
  类型： 字符串：实体名称。
- viewDisplayName
  类型： 字符串：视图名称。
- fetchXML
  字符串：视图的 fetchXml 查询。
- layoutXml
  类型： 字符串：定义视图布局的 XML。
- 默认
  类型： 布尔：视图是否应该是默认视图。

备注
此方法不适用于“负责人”查找。所有人查找用于分派用户拥有的记录。

DefaultView

您可以使用 getDefaultView 和 setDefaultView，检测哪些视图是显示的默认视图，允许用户在查找中选择记录并更改默认视图。

getDefaultView

返回默认查找对话视图的 ID 值。

Xrm.Page.getControl(arg).getDefaultView()

返回值
类型： 字符串。默认视图的 ID 值。

setDefaultView

设置查找控件对话框的默认视图。

Xrm.Page.getControl(arg).setDefaultView(viewGuid)

参数
类型： 字符串。将视图的 ID 设置为默认视图。

示例：该 setDefaultViewSample 函数将 account 实体窗体主要联系人查找默认视图设置为我的可用联系人视图。

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

PreSearch 事件

使用 addPreSearch 和 removePreSearch 方法，您可以添加或移除查找控件 PreSearch 事件中的事件处理程序。

使用 PreSearch 事件来控制当用户开始搜索记录，控件使用当前窗体数据所显示的结果。

这两种方法都将执行上下文（客户端引用）传递为第一个参数。

addPreSearch

当用户将显示查找的结果时，可使用此方法基于当前值应用对查找所做的更改。

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

参数
类型： 要添加的函数。
备注
本方法仅用于更新的实体。

此参数为搜索之前要运行的以提供查询结果的函数。您可以使用此处理程序调用其他某个查找控件函数和改进在查找中显示的结果。

removePreSearch

使用此方法删除为 PreSearch 事件之前设置的事件处理程序函数。

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

参数
类型： 要删除的函数。
备注
本方法仅用于更新的实体。

通知

使用 setNotification 显示有关控件的通知和使用 clearNotification 以删除该通知。

setNotification

在控件旁显示消息，指示数据无效。当该方法在适用于平板电脑的 Microsoft Dynamics CRM 上使用时，一个红色的“X”图标显示在控件旁边。点按图标将显示消息。

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

备注

在控件上设置一个通知将禁止保存表单。

本方法仅用于更新的实体。

参数

消息
类型： 字符串：要显示的消息。
uniqueId
类型： 字符串：使用 clearNotification 用以清除此消息的 ID。

返回值

类型： 布尔：指示方法是否成功。

clearNotification

删除已为控件显示的消息。

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

参数

uniqueId
类型： 字符串：使用 setNotification 用以清除特定消息设置的 ID。

如果未使用 uniqueId 参数，将删除显示的当前通知。

备注

本方法仅用于更新的实体。

返回值

类型： 布尔：指示方法是否成功。

OptionSet 控件方法

使用 addOption、clearOptions 和 removeOption 方法操作适用于 OptionSet 控件的选项。有关使用这些函数的示例，请参阅示例：创建从属选项集（选择列表）。

addOption

向选项集控件添加选项

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

重要

此方法不会检查您添加的选项中的值是否有效。如果添加无效的选项，则它们不会正常工作。您只能添加控件被绑定到的为指定选项集属性定义的选项。使用属性 getOptions 或 getOption 方法来获取有效选项对象，然后使用此方法进行添加。

参数
- 选项
  类型： 对象：添加到 OptionSet 的选项对象。
- 索引
  类型： 数量：（可选）放置新选项的索引位置。如果不提供，选项将添加到结尾。

clearOptions

从选项集控件清除所有选项。

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

removeOption

从选项集控件删除某个选项。

Xrm.Page.getControl(arg).removeOption(number)

参数
类型：数量：要移除的选项值。

setFocus

在控件上设置焦点。

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

ShowTime

使用 setShowTime 指定日期控件是否应显示日期的时间部分，使用 Microsoft Dynamics CRM Online 2015 更新 1 或更高版本，使用 getShowTime 确定日期的时间部分当前是否显示。

getShowTime

了解日期控件是否显示日期的时间部分。

控件类型：datetime 属性的标准控件。

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

备注

此方法与 Microsoft Dynamics CRM Online 2015 更新 1 一同引入。

setShowTime

指定日期控件是否应显示日期的时间部分。

控件类型：datetime 属性的标准控件。

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

备注

本方法仅用于更新的实体。此方法将显示或隐藏日期控件的时间组件，其属性使用 DateAndTime 格式。使用 DateOnly 格式对此方法没有影响。

Subgrid 控件方法

对于 Microsoft Dynamics CRM Online 2015 更新 1 之前的版本，唯一可用于子网格控件的方法是 refresh。使用 CRM Online 2015 更新 1，有新功能可以使用。详细信息：网格对象和方法（客户端引用）

refresh

刷新子网格中显示的数据。

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

备注

刷新方法在 OnLoad 事件窗体中不可用，因为子网格异步加载。有了 CRM Online 2015 更新 1 中引入的子网格 OnLoad 事件，现在您可以检测子网格什么时候加载，并将此方法用于该事件的事件处理程序。

可见

确定哪些控件是可见的，然后使用 getVisible 和 setVisible 方法显示或隐藏该控件。

getVisible

返回一个指示控件当前是否可见的值。

备注

如果包含此控件的部分或选项卡不可见，此方法可能仍会返回 true。确保控制实际可见；您还需要检查包含元素的可见性。

Xrm.Page.getControl(arg).getVisible()

返回值
类型： 布尔。如果控件可见，则返回 Truetrue，否则返回 false。

setVisible

设置指示控件是否可见的值。

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

参数
类型： 布尔。如果控件可见，则返回 True，否则返回 false。

备注

在 Onload 事件运行的代码选择性地给用户显示字段时，建议您将字段配置为默认不可见，然后在条件合适时，使用 setVisible(true) 显示该字段。使用 setVisible(false) 隐藏 Onload 事件中的字段可能导致简要给用户显示隐藏前的字段。
如果您使用 setVisible(false) 隐藏大量字段，请考虑是否可以将它们集合到选项卡或部分中，隐藏选项卡或部分而不是隐藏单个字段。这可以提高性能。

Web 资源和 IFRAME 控件方法

使用这些方法与 Web 资源和 IFRAME 控件交互。

备注

这些方法不适用于适用于平板电脑的 Microsoft Dynamics CRM。

数据

Web 资源有一个名为 data 的特殊查询字符串参数来传递自定义数据。getData 和 setData 方法只适用于添加到窗体的 Silverlight web 资源。详细信息：从窗体向嵌入的 Silverlight Web 资源传递数据

对于网页 (HTML) web 资源，可通过 getSrc 方法提取数据参数或者使用setSrc 方法设置数据参数。

getData

返回传递给 Silverlight web 资源的数据查询字符串参数的值。

Xrm.Page.getControl(arg).getData()

返回值
类型： 字符串。数据值被传递给 Silverlight web 资源。

setData

设置传递给 Silverlight web 资源的数据查询字符串参数的值。

Xrm.Page.getControl(arg).setData(string)

参数
类型： 字符串。数据值待传递给 Silverlight web 资源。

getInitialUrl

返回 IFRAME 控件配置为显示的默认 URL。此方法不适用于 Web 资源。

Xrm.Page.getControl(arg).getInitialUrl()

返回值
类型： 字符串。初始 URL。

getObject

返回在窗体中代表 I-frame 或 Web 资源的对象。

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

返回值
类型： 对象。对象取决于控件的类型。

IFRAME 将从文档对象模型 (DOM) 返回 IFrame 元素。

Silverlight web 资源将从代表嵌入的 Silverlight 插件的 DOC 返回对象元素。

Src

IFrame 或 Web 资源中嵌入的窗口都有一个 src 定义显示内容的属性。使用 getSrc 和setSrc 方法，您可以获取或更改 src 属性。

getSrc

返回 IFRAME 或 web 资源中显示的当前 URL。

Xrm.Page.getControl(arg).getSrc()

返回值
类型： 字符串。URL 代表 IFRAME 或 web 资源的 src 属性。

setSrc

设置 IFRAME 或 web 资源中将要显示的 URL。

Xrm.Page.getControl(arg).setSrc(string)

参数
类型： 字符串：URL。

另请参阅

客户端编程引用
 脚本即时引用的表单
 Xrm.Page.ui（客户端引用）
为 Microsoft Dynamics CRM 2015 窗体编写代码
 使用 Xrm.Page 对象模型

Share via

Xrm.Page.ui 控制方法（客户端引用）

控件属性和方法

已禁用

getDisabled

setDisabled

getAttribute

getControlType

getName

getParent

知识库控件方法

标签

getLabel

setLabel

Lookup 控件方法和事件

addCustomFilter

addCustomView

DefaultView

getDefaultView

setDefaultView

PreSearch 事件

addPreSearch

removePreSearch

通知

setNotification

clearNotification

OptionSet 控件方法

addOption

clearOptions

removeOption

setFocus

ShowTime

getShowTime

setShowTime

Subgrid 控件方法

refresh

可见

getVisible

setVisible

Web 资源和 IFRAME 控件方法

数据

getData

setData

getInitialUrl

getObject

Src

getSrc

setSrc

另请参阅

其他资源