脚本即时引用的表单

  • 项目

 

发布日期： 2017年1月

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

本主题根据您使用常用窗体脚本方法执行的任务，提供这些方法的快速参考。 有关完整参考，请参阅客户端编程引用。 除非另行说明，此页上的所有示例将使用默认客户实体主窗体。

本主题内容

属性

  • 访问属性

  • 获取或设置实体属性数据

  • 获取属性元数据

保存事件参数

显示通知

控件

  • 访问窗体控件

  • 访问标题控件

  • 访问业务流程控件

  • 窗体控件方法

  • OptionSet 控件方法

  • IFRAME 和 web 控件方法

  • 查找控件方法

  • SubGrid 控件方法

  • 日期控件方法

窗体导航

选项卡和章节

运行时添加或删除事件处理程序

上下文信息方法

获取、刷新或保存实体数据

属性

属性存储数据中的可用记录。

访问属性

可以从 Xrm.Page.data.entity.attributes 集合中获得属性。 若要访问属性，可以使用 **Xrm.Page.data.entity.attributes.**9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get 方法或快捷版本 Xrm.Page.getAttribute。get 方法接受四种类型的参数：

  • 字符串： 返回属性名称与字符串匹配的属性对象。

  • 编号： 返回 Xrm.Page.data.entity.attributes 集合索引与编号匹配的属性对象。

  • 无： 返回所有属性的数组。

  • Delegate function(attribute,index): 返回 Xrm.Page.data.entity.attributes 集合中导致委托函数返回 true 的所有属性的数组。

任务

示例

按名称访问属性

var nameAttribute = Xrm.Page.getAttribute("name");

将“客户名称”字段的属性分配给 nameAttribute 变量

按索引访问属性

var firstAttribute = Xrm.Page.getAttribute(0);

将 Xrm.Page.data.entity.attributes 集合中的第一个属性分配给 firstAttribute 变量。

访问所有属性

var allAttributes = Xrm.Page.getAttribute();

将 Xrm.Page.data.entity.attributes 集合中所有属性的数组分配给 allAttributes 变量。

访问符合特定条件的所有属性

var optionsetAttributes = Xrm.Page.getAttribute(function (attribute, index) {
return attribute.getAttributeType() == "optionset";
});

将 Xrm.Page.data.entity.attributes 集合中符合匿名函数中设置的条件（当属性类型为“optionset”时返回 true）的所有属性的数组分配给 optionsetAttributes 变量。

Xrm.Page.data.entity.attributes 集合还有可用来访问函数中的属性的 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach 方法。 以下 writeRequiredAttributesToConsole 函数将需要数据的所有属性的名称写入调试控制台：

function writeRequiredAttributesToConsole() {
 var requiredAttributeNames = [];

 Xrm.Page.data.entity.attributes.forEach(
 function (attribute, index) {
  if (attribute.getRequiredLevel() == "required")
  { requiredAttributeNames.push(attribute.getName()); }
 });

 if (requiredAttributeNames.length > 0) {
  if (typeof console != "undefined") {
   console.log(requiredAttributeNames.join());
  }
 }
 else {
  if (typeof console != "undefined") {
   console.log("No required attributes detected");
  }
 }
}

本主题内容

获取或设置实体属性数据

下表中的示例演示如何检索或更改属性中存储的数据。

任务

方法

示例

获取属性的值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getValue

var nameValue = Xrm.Page.getAttribute("name").getValue();

将“客户名称”字段的值分配给 nameValue 变量

设置属性的值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setValue

Xrm.Page.getAttribute("name").setValue("new name");

将“客户名称”字段的值设置为“new name”。

获取选项集属性的当前选定选项的文本值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getText

var addressType = Xrm.Page.getAttribute("address1_addresstypecode").getText();

将“地址类型”字段中选定选项的文本分配给 addressType 变量。

获取 optionset 属性中当前选定选项对象

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSelectedOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getSelectedOption();

将“地址类型”字段中的选定选项分配给 addressTypeOption 变量。

本主题内容

获取属性元数据

下表中的示例演示如何查询属性以了解属性类型或更改属性的行为。

任务

方法

示例

获取属性的类型

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getAttributeType

var attributeType = Xrm.Page.getAttribute(0).getAttributeType();

将代表第一个属性的属性类型的字符串值分配给 attributeType 变量。

获取属性的格式化方式

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getFormat

var attributeFormat = Xrm.Page.getAttribute(0).getFormat();

将代表第一个属性的格式的字符串值分配给 attributeFormat 变量。

获取 Boolean 或 optionset 属性的初始值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getInitialValue

var attributeInitialValue = Xrm.Page.getAttribute("address1_addresstypecode").getInitialValue();

将“地址类型”字段的初始编号值分配给 attributeInitialValue 变量。

确定属性值是否已更改

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsDirty

var isNameChanged = Xrm.Page.getAttribute("name").getIsDirty();

将指示“客户名称”字段值是否已更改的 Boolean 值分配给 isNameChanged 变量。

确定查找属性是否表示 PartyList 查找。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getIsPartyList

var isPartyList = Xrm.Page.getAttribute("to").getIsPartyList();

给 Boolean 指定一个值，用来指示“将电子邮件”实体“发送到”字段是否表示 partylist 查找。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

获取包含数字的属性的最大允许值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMax

var newValue = 100000000000001;
var newValueBelowMax = (newValue < Xrm.Page.getAttribute("creditlimit").getMax())

将指示 newValue 变量的值是否超过“信用额度”字段最大允许值的 Boolean 值分配给 newValueBelowMax 变量。

获取包含字符串的属性的最大允许长度

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMaxLength

var newAccountName = "A Store";
var nameTooLong = (newAccountName.length > Xrm.Page.getAttribute("name").getMaxLength())

将指示 newAccountName 变量的值是否超过“客户名称”字段最大允许长度的 Boolean 值分配给 nameTooLong 变量。

获取包含数字的属性的最小允许值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getMin

var newValue = -1;
var newValueBelowMin = (newValue < Xrm.Page.getAttribute("creditlimit").getMin())

将指示 newValue 变量的值是否低于“信用额度字段最小允许值的 Boolean 值分配给 newValueBelowMin 变量。

获取属性的逻辑名称

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getName

var attributeName = Xrm.Page.getAttribute(0).getName();

将页面中第一个属性的逻辑名称值分配给 attributeName 变量。

获取表示值的选项对象

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption

var addressTypeOption = Xrm.Page.getAttribute("address1_addresstypecode").getOption(1);
alert(addressTypeOption.text); //displays 'Bill To'

显示一个警报，其中显示了值为 1 的“地址类型”字段选项的文本。

获取表示数字属性的精度级别的数值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getPrecision

var creditLimitPrecision = Xrm.Page.getAttribute("creditlimit").getPrecision();

将“信用额度”字段的精度值分配给 creditLimitPrecision 变量

获取表示是否要求属性中存在值的字符串值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getRequiredLevel

var creditLimitRequired = Xrm.Page.getAttribute("creditlimit").getRequiredLevel();

creditLimitRequired 变量值可以为 none、required 或 recommended。

更改字段中是否需要数据以保存记录

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setRequiredLevel

Xrm.Page.getAttribute("creditlimit").setRequiredLevel("required");

根据需要进行“信用额度”字段的更改。

确定当保存记录时是否提交属性中的数据

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getSubmitMode

var nameSubmitMode = Xrm.Page.getAttribute("name").getSubmitMode();

nameSubmitMode 变量值将为 always、never 或 dirty 以表示“客户名称”字段的 submitMode。

控制当保存记录时是否将保存属性中的数据

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_setSubmitMode

Xrm.Page.getAttribute("name").setSubmitMode("always");

该示例将强制始终保存“客户名称”字段值，即使它未更改。

当字段级安全性应用于属性时，
请确保用户是否有权对属性执行创建、
读取或更新操作。 有关详细信息，请参阅
在 Microsoft Dynamics 365 中，如何将字段安全用于控制访问字段值

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getUserPrivilege

var canUpdateNameAttribute = Xrm.Page.getAttribute("name").getUserPrivilege().canUpdate;

将表示用户更新“客户名称”字段的权限的 Boolean 值分配给 canUpdateNameAttribute 变量。

本主题内容

保存事件参数

在实施业务逻辑时，通常有需要阻止保存记录，以便用户可以包含必需的信息。 为此，您必须配置要在执行上下文中传递的事件处理程序。 执行上下文包含 getEventArgs 方法以检索事件的参数。 这些参数包括一些方法，可用来控制是否保存记录或者查询让您了解 save 事件的属性。

任务

示例

阻止保存记录。

function My_PreventSaveFunction(eContext) {
 eContext.getEventArgs().preventDefault();
}

使用 eContext 参数捕获执行上下文，并使用事件参数附带的 preventDefault 方法。

确定启动保存的操作。

function My_GetSaveModeTextFunction(eContext) {
 var saveModeCode = eContext.getEventArgs().getSaveMode();
 var saveModeText = "Unknown";
 switch (saveModeCode) {
  case 1:
   saveModeText = "Save";
   break;
  case 2:
   saveModeText = "SaveAndClose";
   break;
  case 5:
   saveModeText = "Deactivate";
   break;
  case 6:
   saveModeText = "Reactivate";
   break;
  case 7:
   saveModeText = "Send";
   break;
  case 15:
   saveModeText = "Disqualify";
   break;
  case 16:
   saveModeText = "Qualify";
   break;
  case 47:
   saveModeText = "Assign";
   break;
  case 58:
   saveModeText = "SaveAsCompleted";
   break;
  case 59:
   saveModeText = "SaveAndNew";
   break;
  case 70:
   saveModeText = "AutoSave";
   break;
 }
 return saveModeText;
}

使用 eContext 参数捕获执行上下文，并使用事件参数附带的 getSaveMode 方法将整数代码值转换为文本。

本主题内容

显示通知

通知提供了一种向用户显示消息的途径。

任务

方法

示例

在控件旁显示消息，指示数据无效。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.setNotification("'Test' is not a valid name.");
})

在窗体中的每个控件上为“客户名称”属性设置一个验证出错消息。

虽然显示该消息，但是不能保存记录。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

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

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearnotification

Xrm.Page.getAttribute("name").controls.forEach(
function (control, i) {
control.clearNotification();
})

在窗体中清除每个控件上的“客户名称”属性的所有验证出错消息。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

显示窗体级别通知。

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_setFormNotification

Xrm.Page.ui.setFormNotification(
"Hello",
"INFO",
"helloMsg"
);

用系统消息图标在表单顶部显示消息“你好”。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

删除窗体级别通知。

0375b206-d2bf-4034-a41d-fb476ecb4438#BKMK_clearFormNotification

Xrm.Page.ui.clearFormNotification("helloMsg");

将“helloMsg”用作 uniqueid 参数，清除之前设置的消息。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

使用回调函数显示无阻塞警报对话框。

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_alertDialog

var alertDisplayed = false;
Xrm.Utility.alertDialog(
"Showing Alert",
function () { alertDisplayed = true; }
)

显示警报，并在关闭 alertDisplayed 后设置其变量值。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

根据用户单击的按钮，使用不同的回调函数显示无阻塞确认对话框。

72a66f93-92df-42b9-a8fd-b6125c7fe83b#BKMK_confirmDialog

var agree = false;
Xrm.Utility.confirmDialog(
"Do you agree?",
function () { agree = true;},
function () { agree = false; }
);

显示确认消息，并根据响应设置 agree 变量的值。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

本主题内容

控件

控件代表窗体中的用户界面元素。 窗体中的每个属性至少有一个与它关联的控件。 并非每个控件都与属性关联。IFRAME、Web 资源和子网格是没有属性的控件。

访问窗体控件

可以从 Xrm.Page.ui.controls 集合获取控件。 若要访问控件，可以使用 Xrm.Page.ui.controls.9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get 方法或快捷版本 Xrm.Page.getControl。

获取方法接受四种类型的参数：

  • 字符串： 返回逻辑名称与字符串匹配的控件。

  • 编号： 返回 Xrm.Page.ui.controls 集合索引与编号匹配的控件。

  • 无： 返回所有控件的数组。

  • Delegate function(control,index): 返回 Xrm.Page.ui.controls 集合中导致委托函数返回 true 的所有控件的数组。

任务

示例

访问特定属性的所有控件

var nameControls = Xrm.Page.getAttribute("name").controls.get();

将 name 属性的所有控件的数组分配给 nameControls 变量。

按名称访问控件

var nameControl = Xrm.Page.getControl("name");

将表示“客户名称”字段的第一个控件分配给 nameControl 变量。

添加到属性的窗体的第一个控件具有与属性相同的名称。 每个附加控件名称在名称中都附加了索引编号。 例如，名称属性的三个控件分别具有以下名称：name、name1 和 name2。

按索引访问控件

var firstControl = Xrm.Page.getControl(0);

将 Xrm.Page.ui.controls 集合中的第一个控件分配给 firstControl 变量。

访问所有控件

var allControls = Xrm.Page.getControl();

将 Xrm.Page.ui.controls 集合中所有控件的数组分配给 allControls 变量。

访问符合特定条件的所有控件

var optionsetControls = Xrm.Page.getControl(function (control, index) {
return control.getControlType() == "optionset";
});

将 Xrm.Page.ui.controls 集合中符合匿名函数中设置的条件（当控件类型为“optionset”时返回 true）的所有属性的数组分配给 optionsetControls 变量。

每个部分还包含一个控件集合，该集合中仅包含该部分的控件。 以下代码示例将 generalTabAccountInfoSectionControls 变量分配给“常规”选项卡的“地址”部分中的控件数组。
var generalTabAccountInfoSectionControls = Xrm.Page.ui.tabs.get("general").sections.get("address").controls.get();

备注

每个属性只能在窗体中出现一次，但是可以通过将字段添加到窗体，从而多次显示该属性。 添加的每个字段都会创建另一个控件。 编写脚本后，可以进一步自定义窗体。 编写的属性控制脚本应该假定被窗体多次包含。 对一个属性的控件所执行的任何操作通常都应应用到该属性的所有控件。 例如，如果想禁用某个控件，但是只禁用了其中的一个，用户仍然可以使用其他控件输入数据。 因此，即使您在编写脚本时只有一个控制，也建议您使用以下模式的集合 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach 方法将同一种逻辑应用到属性的所有控件中。

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

本主题内容

访问标题控件

标题中的控件遵循此命名规则，其中“header_”是控件名称的前缀。 例如，如果 name 属性位于标题中，则您可以使用
var nameControlInHeader = Xrm.Page.getControl("header_name"); 对其进行访问。

访问业务流程控件

业务流程控件中的控件遵循此命名规则，其中“header_process_”是控件名称的前缀。 例如，如果 name 属性位于标题中，则您可以使用
var nameControlInBPF = Xrm.Page.getControl("header_process_name"); 对其进行访问。

备注

当窗体加载时，只有活动阶段的控件位于 Xrm.Page.ui.controls 集合中。 当选择当前实体的阶段时，将添加其他业务流程控件。

窗体控件方法

在您有权访问控件后，可以调用以下方法。

任务

方法

示例

确定控件是否可见

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getVisible

var isNameVisible = Xrm.Page.getControl("name").getVisible();

将 Boolean 值分配给表示“客户名称”字段值是否可见的 isNameVisible 变量。

隐藏或显示控件

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setVisible

Xrm.Page.getControl("name").setVisible(false);

隐藏“客户名称”字段。

获取对控件属性的引用

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getAttribute

var nameAttribute = Xrm.Page.getControl("name").getAttribute();

将“客户名称”字段的控件属性分配给 nameAttribute 变量。

备注

并非所有控件都具有属性。

确定控件的类型

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getControlType

var optionSetControls = Xrm.Page.getControl(function (control, index) { return control.getControlType() == "optionset"; });

将 optionset 控件的数组分配给 optionSetControls 变量。

确定控件是否已启用

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDisabled

var disabledControls = Xrm.Page.getControl(function(control, index) { return control.getDisabled(); });

将已禁用控件的数组分配给 disabledControls 变量。

备注

Web 资源和子网格控件不支持此方法。

禁用或启用控件

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDisabled

Xrm.Page.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); });

禁用 name 属性的每个控件。

提示

请记住，任何属性都可以具有多个控件。

获取控件的标签

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getLabel

var nameControlLabel = Xrm.Page.getControl("name").getLabel();

将“客户名称”字段的控件值分配给 nameControlLabel 变量。

更改控件的标签

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setLabel

Xrm.Page.getControl("name").setLabel("Company Name");

将“客户名称”字段的标签更改为“公司名称”。

获取控件的名称

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getName

var firstControlName = Xrm.Page.getControl(0).getName();

将 Xrm.Page.ui.controls 集合中第一个控件的名称分配给 firstControlName 变量。

获取控件的父级

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getParent

var parentSection = Xrm.Page.getControl("name").getParent();

将“客户名称”字段的控件父部分分配给 parentSection 变量。

设置控件上的焦点

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setFocus

Xrm.Page.getControl("name").setFocus();

设置“客户名称”字段上的焦点。

本主题内容

OptionSet 控件方法

选项集有一些特殊方法。 有必要记住，属性定义 optionset 的有效选项。 当您使用 optionset 控件时，可以操作可用选项，但是不能创建新选项。

任务

方法

示例

向选项集控件添加选项

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addOption

var addressTypeCodeControl = Xrm.Page.getControl("address1_addresstypecode");
var billToAddressOption = addressTypeCodeControl.getAttribute().getOption(1);
addressTypeCodeControl.clearOptions();
addressTypeCodeControl.addOption(billToAddressOption);

使用对“地址类型”字段的控件的引用，访问控件的属性并使用 6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_getOption 方法将 billToAddressOption 变量设置为表示“帐单邮寄地址”选项的选项。

使用 51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions 删除所有现有的选项并使用 addOption 将 billToAddressOption 设置为可用于此控件的唯一选项。

从选项集控件删除所有选项

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_clearOptions

Xrm.Page.getControl("address1_addresstypecode").clearOptions();

从“地址类型”字段的控件删除所有选项。

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

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_removeOption

Xrm.Page.getControl("address1_addresstypecode").removeOption(1);

从“地址类型”字段的控件删除“帐单邮寄地址”选项。

本主题内容

IFRAME 和 web 控件方法

IFRAME 控件允许通过提供 URL 在窗体中包含页面。 添加到窗体的 HTML Web 资源是使用 IFRAME 元素呈现的。Silverlight 和图像 Web 资源会直接嵌入页面中。

任务

方法

示例

获取传递给 Silverlight Web 资源的数据查询字符串参数的值。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getData

var dataValue = Xrm.Page.getControl("WebResource_SilverLightControl").getData();

将通过数据查询字符串参数传递的值分配给 dataValue 变量。

获取 IFRAME 中当前显示的内容的 URL。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getSrc

var iframeSource = Xrm.Page.getControl("IFRAME_targetPage").getSrc();

将表示当前 IFRAME.src 属性值的字符串分配给 iframeSource 变量。

设置要在 IFRAME 中显示的内容的 URL。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setSrc

Xrm.Page.getControl("IFRAME_targetPage").setSrc("http://www.bing.com");

设置要成为控件的 IFRAME.src 的 URL。

获取表示 IFRAME 的默认配置 URL 的 URL。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getUrl

var initialUrl = Xrm.Page.getControl("IFRAME_bing").getInitialUrl();

将配置为要在 IFRAME 中显示的初始 URL 分配给 initialUrl 变量。

获取表示 Web 资源或 IFRAME 的窗体中的对象。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getObject

var obj = Xrm.Page.getControl("IFRAME_bing").getObject();

将对象引用分配给 obj 变量。 对于 IFRAME，它将是 IFRAME 文档对象模型 (DOM) 元素。 对于 Silverlight Web 资源，它将是代表嵌入的 Silverlight 插件的对象 对象 元素。

本主题内容

查找控件方法

查找控件的常见要求是指定当用户更新字段时显示的默认视图。

任务

方法

示例

添加查找的自定义视图。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
var viewDisplayName = "SDK Sample View";
var fetchXml = "<fetch version='1.0' " +
"output-format='xml-platform' " +
"mapping='logical'>" +
"<entity name='account'>" +
"<attribute name='name' />" +
"<attribute name='address1_city' />" +
"<order attribute='name' " +
"descending='false' />" +
"<filter type='and'>" +
"<condition attribute='ownerid' " +
"operator='eq-userid' />" +
"<condition attribute='statecode' " +
"operator='eq' " +
"value='0' />" +
"</filter>" +
"<attribute name='primarycontactid' />" +
"<attribute name='telephone1' />" +
"<attribute name='accountid' />" +
"<link-entity "+
"alias='accountprimarycontactidcontactcontactid' " +
"name='contact' " +
"from='contactid' " +
"to='primarycontactid' " +
"link-type='outer' " +
"visible='false'>" +
"<attribute name='emailaddress1' />" +
"</link-entity>" +
"</entity>" +
"</fetch>";
var layoutXml = "<grid name='resultset' " +
"object='1' " +
"jump='name' " +
"select='1' " +
"icon='1' " +
"preview='1'>" +
"<row name='result' " +
"id='accountid'>" +
"<cell name='name' " +
"width='300' />" +
"<cell name='telephone1' " +
"width='100' />" +
"<cell name='address1_city' " +
"width='100' />" +
"<cell name='primarycontactid' " +
"width='150' />" +
"<cell name='accountprimarycontactidcontactcontactid.emailaddress1' " +
"width='150' " +
"disableSorting='1' />" +
"</row>" +
"</grid>";
Xrm.Page.getControl("parentaccountid").addCustomView(viewId, "account", viewDisplayName, fetchXml, layoutXml, true);

设置作为参数传递的 viewId、viewDisplayName、fetchXml 和 layoutXml 变量，以便自定义视图作为默认视图添加到“上级单位”查找字段的控件。

获取查找的默认视图。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_getDefaultView

var defaultViewId = Xrm.Page.getControl("parentaccountid").getDefaultView();

将默认视图的 id 的值分配给 defaultViewId 变量。

设置查找的默认视图。

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setDefaultView

var viewId = "{C7034F4F-6F92-4DD7-BD9D-9B9C1E996380}";
Xrm.Page.getControl("parentaccountid").setDefaultView(viewId);

将“上级单位”字段控件的默认视图设置为 viewId 变量中的 id 值。

为查找控件筛选返回的记录

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addCustomFilter

以下代码示例适用于商机窗体“客户” (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);
}

本主题内容

SubGrid 控件方法

SubGrid 控件是窗体中的网格。 它具有一个唯一方法。

任务

方法

示例

刷新子网格中显示的数据

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_refresh

Xrm.Page.getControl("accountcontactsgrid").refresh();

刷新“联系人”subgrid。

本主题内容

日期控件方法

日期控件有一个唯一的方法。

任务

方法

示例

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

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_setShowTime

Xrm.Page.getControl("createdon").setShowTime(false);

将字段设置为“创建于”可以不显示时间。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

本主题内容

窗体导航

您可以使用和操作窗体左侧的导航项。 这些导航项通常显示与窗体中显示的记录有关的记录。

您可以使用 Xrm.Page.ui.navigation.items 集合访问导航项。像窗体中的所有集合一样，提供了 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_get 和 9b85e46f-ca6e-4313-af04-4290e3c6ab8b#BKMK_forEach 方法。

任务

方法

示例

获取导航项的名称

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getId

var navItemIds = [];
Xrm.Page.ui.navigation.items.forEach(
function (item, index)
{ navItemIds.push(item.getId()) }
);

创建 navItemIds 数组，其中包含 Xrm.Page.ui.navigation.items 集合中每个导航项的 id 值。

获取导航项的标签。

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getLabel

var navAddressesLabel = Xrm.Page.ui.navigation.items.get("navAddresses").getLabel();

将“更多地址”导航项的标签分配给 navAddressesLabel 变量。

设置导航项的标签

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setLabel

Xrm.Page.ui.navigation.items.get("navAddresses").setLabel("Other Addresses");

将“更多地址”导航项标签更改为“其他地址”。

显示或隐藏导航项

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setVisible

Xrm.Page.ui.navigation.items.get("navAddresses").setVisible(false);

隐藏 More Addresses 导航项。

确定导航项是否可见

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_getVisible

var moreAddressesVisible = Xrm.Page.ui.navigation.items.get("navAddresses").getVisible()

将 Boolean 值分配给 moreAddressesVisible 变量以表示“更多地址”导航项是否可见。

设置导航项上的焦点。

bcf7210d-df71-43a5-8052-a76de0d4763d#BKMK_setFocus

Xrm.Page.ui.navigation.items.get("navAddresses").setFocus();

设置“更多地址”导航项上的焦点。

本主题内容

选项卡和章节

每个窗体都有选项卡集合。 每个选项卡都有部分的集合。 每个部分都有控件的集合。 可通过编程方式访问这些元素以及使用它们的方法。

任务

方法

示例

确定选项卡是展开还是折叠

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_getDisplayState

var isGeneralTabExpanded = (Xrm.Page.ui.tabs.get("general").getDisplayState() == "expanded")

将 Boolean 值分配给指示“常规”选项卡是否展开的 isGeneralTabExpanded 变量。

展开或折叠选项卡

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetDisplayState

Xrm.Page.ui.tabs.get("general").setDisplayState("collapsed");

折叠“常规”选项卡。

确定选项卡是否可见

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetVisible

var isGeneralTabVisible = Xrm.Page.ui.tabs.get("general").getVisible();

将 Boolean 值分配给指示“常规”选项卡是否可见的 isGeneralTabVisible 变量。

显示或隐藏选项卡

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetVisible

Xrm.Page.ui.tabs.get("general").setVisible(false);

隐藏“常规”选项卡。

获取选项卡的标签

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetLabel

var generalTabLabel = Xrm.Page.ui.tabs.get("general").getLabel();

将“常规”选项卡标签分配给 generalTabLabel 变量。

更改选项卡的标签

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetLabel

Xrm.Page.ui.tabs.get("general").setLabel("Major");

将“常规”选项卡标签更改为“主要”。

设置选项卡上的焦点

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabsetFocus

Xrm.Page.ui.tabs.get("general").setFocus();

设置“常规”选项卡上的焦点。

获取选项卡的名称

205390b9-3eda-4a2b-87cb-2a8f83f953da#BKMK_tabgetName

var firstTabName = Xrm.Page.ui.tabs.get(0).getName();

将第一个选项卡的名称分配给 firstTabName 变量。

获取部分的父选项卡

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetParent

Xrm.Page.getControl("industrycode").getParent().getParent().setFocus();

设置包含“行业”字段的选项卡上的焦点。

确定部分是否可见

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionGetVisible

var industrySectionVisible = Xrm.Page.getControl("industrycode").getParent().getVisible();

将 Boolean 值分配给指示包含“行业”字段的部分是否可见的 industrySectionVisible 变量。

显示或隐藏部分

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetVisible

Xrm.Page.getControl("industrycode").getParent().setVisible(false);

隐藏包含“行业”字段的部分。

获取部分的标签

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_getLabel

var industryFieldSectionLabel = Xrm.Page.getControl("industrycode").getParent().getLabel();

将包含“行业”字段的部分的标签分配给 industryFieldSectionLabel 变量。

更改部分的标签

a90df20b-42a6-444e-9912-e0ffab11daec#BKMK_sectionSetLabel

Xrm.Page.getControl("industrycode").getParent().setLabel("Detailed Information");

将包含“行业”字段的部分的标签更改为“详细信息”。

本主题内容

运行时添加或删除事件处理程序

通常使用应用程序中的窗体编辑器来配置事件处理程序，但是您也可以使用这些 APIs 在运行时将它们添加到窗体 OnSave 事件和属性 OnChange 事件。 本节中的示例将引用以下函数定义：
function myFunction() {
//perform action here
}

尽管您可以添加匿名函数，但是函数必须具有引用的名称才能将其删除。

任务

方法

示例

将函数添加到 OnSave 事件

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_addOnSave

Xrm.Page.data.entity.addOnSave(myFunction);

将 myFunction 函数添加到 OnSave 事件。

从 OnSave 事件删除函数

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_removeOnSave

Xrm.Page.data.entity.removeOnSave(myFunction);

将 myFunction 函数删除到 OnSave 事件。

将函数添加到属性的 OnChange 事件。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_addOnChange

Xrm.Page.getAttribute("name").addOnChange(myFunction);

将 myFunction 函数添加到“客户名称”字段的 OnChange 事件

从属性的 OnChange 事件中删除函数。

6881e99b-45e4-4552-8355-2eef296f2cd8#BKMK_removeOnChange

Xrm.Page.getAttribute("name").removeOnChange(myFunction);

将 myFunction 函数删除到“客户名称”字段的 OnChange 事件

将函数添加到查找控件的 PreSearch 事件

51828fe3-f6ff-4f97-80ed-b06b3a354955#BKMK_addPreSearch

以下代码示例适用于商机窗体“客户” (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);
}

使用业务流程控件中产生事件的 d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageChange and d88d5f21-6385-443b-91f2-0ec0c16b1324#BKMK_OnStageSelected。 这些事件仅具有以编程方式添加和删除事件处理程序的方法。详细信息：管理事件处理程序的方法。

本主题内容

上下文信息方法

使用这些方法获取有关用户、组织和客户端的信息。 下表提供一些最有用的上下文方法。 有关所有上下文方法，请参阅客户端上下文（客户端引用）

任务

方法

示例

获取用于连接到组织的 URL。

getClientUrl

var serverUrl = Xrm.Page.context.getClientUrl();

将表示 URL 的字符串分配给 serverUrl 变量。

获取当前用户的唯一标识符。

getUserId

var userId = Xrm.Page.context.getUserId();

将表示用户 Id 的字符串分配给 userId 变量。

获取当前用户的名称。

getUserName

var userName = Xrm.Page.context.getUserName();

将表示用户名的字符串分配给 userName 变量。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

获取表示用户的首选用户界面语言的语言代码。

getUserLcid

var userLCID = Xrm.Page.context.getUserLcid();

将示用户首选语言的数字分配给 userLCID 变量。

获取字符串数组，它们表示分配给当前用户和该用户关联的所有团队的每个安全角色的 GUID 值。

getUserRoles

var userRoles = Xrm.Page.context.getUserRoles();

将表示用户安全角色的字符串数组分配给 userRoles 变量。

确定脚本是否在 Microsoft Dynamics 365 for Outlook 客户端中运行。

客户。getClient

var isOutlookClient = (Xrm.Page.context.client.getClient() == "Outlook");

将表示您的代码是否在 Dynamics 365 for Outlook 客户端中运行的 Boolean 值分配给 isOutlookClient 变量。

确定用户是否正在使用 带脱机访问功能的 Microsoft Dynamics 365 for Microsoft Office Outlook 客户端脱机工作。

客户。getClientState

var IsOffline = (Xrm.Page.context.client.getClientState() == "Offline");

将表示用户当前是否脱机工作的 Boolean 值分配给 IsOffline 变量。

本主题内容

获取、刷新或保存实体数据

下表包含的方法可用于获取当前记录的相关信息，或保存更改。 有关详细信息，请参阅 Xrm.Page.data.entity（客户端引用）和Xrm.Page.data（客户端引用）。

任务

方法

示例

获取当前实体的逻辑名称

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getEntityName

var entityName = Xrm.Page.data.entity.getEntityName();

将逻辑实体名称分配给 entityName 变量。

获取当前实体的主要属性值。
主属性是用于识别记录的值。 例如 contact.fullname。

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getPrimaryAttributeValue

var primaryAttributeValue = Xrm.Page.data.entity.getPrimaryAttributeValue();

将主要属性值分配给 primaryAttributeValue 变量。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

获取当前记录的 Id

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getId

var recordId = Xrm.Page.data.entity.getId();

将记录的 id 分配给 recordId 变量。

异步刷新窗体的数据，而不重新加载页面。

ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_refresh

Xrm.Page.data.refresh();

刷新窗体中的数据。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

保存当前记录

Xrm.Page.data.entity.fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_save

Xrm.Page.data.entity.save();

保存记录。 提供了可选参数。 使用 saveandclose 或 saveandnew 执行等效操作。

使用该选项将
回调函数功能设置成在保存操作完成之后执行，异步保存当前记录。

Xrm.Page.data.ab100e06-a3ba-47f8-a8f8-7b5fab2ab66d#BKMK_dataSave

Xrm.Page.data.save().then(
function(){
Xrm.Utility.alertDialog("Record saved");
},
function(error){
Xrm.Utility.alertDialog(error.message);
});

保存记录，并显示保存状态的消息。

本方法仅用于 41462684-3e5d-4858-8be4-1a7c4fcdeff6#BKMK_UpdatedEntties。

确定当前记录中的任何数据是否已更改。

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getIsDirty

var isDirty = Xrm.Page.data.entity.getIsDirty();

将表示记录中的数据是否已更改的 Boolean 值分配给 isDirty 变量。

获取表示当保存记录时将要发送到服务器的数据的字符串。

fbaf2e7a-db2f-448f-bd24-6b3ca1ccb28e#BKMK_getDataXml

var dataXml = Xrm.Page.data.entity.getDataXml();

将表示要保存的数据的字符串分配给 dataXml 变量。

本主题内容

另请参阅

使用 Xrm.Page 对象模型
为 Microsoft Dynamics 365 窗体编写代码
客户端编程引用

Microsoft Dynamics 365

© 2017 Microsoft。 保留所有权利。 版权