有关使用客户端 API Xrm 对象进行全局操作的简介

已完成

客户端 API 提供 Xrm 对象,该对象在代码中全局可用,无需依赖执行上下文即可执行各种活动。 下图概括说明了可用的每种属性和方法。 有关本对象的深入概述,请参阅客户端 API Xrm 对象。

应用对象

使用应用对象中的 addGlobalNotification,您可以显示应用的错误、信息、警告或成功通知,并根据通知指定要执行的操作。 此通知与窗体通知类似,但可以在窗体上下文之外使用。 例如,命令栏脚本可以通知用户操作已完成。 使用 clearGlobalNotification 方法清除应用中的通知。

设备对象

Xrm.Device 对象公开与移动设备交互相关的本机设备功能,但 pickFile 方法除外,该方法也可通过 Web 客户端访问。 画布应用还提供了可扩展的移动开发框架,应考虑在这些场景中使用。 下表汇总了 Xrm.Device 对象中提供的方法。

方法 描述
captureAudio 调用设备麦克风以录制音频。
captureImage 调用设备相机以捕获图像。
captureVideo 调用设备相机以录制视频。
getBarcodeValue 调用设备相机以扫描条码信息,例如产品编号。
getCurrentPosition 使用设备地理位置功能返回当前位置。
pickFile 打开对话框以从计算机(Web 客户端)或移动设备(移动客户端)选择文件。

根据设备配置,某些功能会不可用。 应用访问特定的设备功能之前,可能还需要征得用户同意。 例如,用户可能全局禁用了设备位置功能或拒绝应用访问相机。 开发应用时,请注意,由于设备功能、配置、权限不足或需征询同意,这些方法都有可能失败。

编码对象

您可以使用 Xrm.Encoding 对象编码和解码 XML 和 HTML 字符串。 在以下情况下,这种编码和解码可能很有用:

  • 与 HTML Web 资源进行交互,

  • 编码和解码查询字符串参数,

  • 与 FetchXML 交互,搜索字符串中包含特殊字符(如“&”或“<”)。

导航对象提供与导航相关的方法,可在模型驱动应用中使用。 显示预警、确认和错误对话框等活动由于其锁定性质,并不被视为最佳用户体验,但仍可供使用。 在这些场景中,我们建议您考虑使用窗体通知,或其他非锁定机制来警告用户出现问题。 下面汇总了 Xrm.Navigation 对象中提供的方法。

方法 描述
openAlertDialog 显示包含消息和按钮的警报对话框。
openConfirmDialog 显示包含消息和两个按钮的确认对话框。
openErrorDialog 显示错误对话框。
openFile 打开文件。
openForm 打开表格窗体或快速创建窗体。
openUrl 打开 URL,包括文件 URL。
openWebResource 打开 HTML Web 资源。

面板对象

Xrm.Panel 对象提供一种在模型驱动应用窗体的侧窗格上显示网页的方法。 本功能当前处于预览阶段,在此处将不详细介绍。 有关详细信息,请参阅 Xrm.Panel。

实用工具对象

Xrm.Utility 对象是各种有用方法的容器。 下表汇总了 Xrm.Utility 对象中提供的方法。 有关详细信息,请参阅 Xrm.Utility(客户端 API 引用)

方法 描述
closeProgressIndicator 指示器将关闭使用 showProgressIndicator 打开的进度对话框。
getAllowedStatusTransitions 返回指定表的有效状态转换和状态代码。
getEntityMetadata 返回指定实体的实体元数据。
getGlobalContext 检索全局上下文,从而提供运行时信息,例如组织设置、用户设置、应用详细信息和客户端信息。
getLearningPathAttributeName 返回学习路径(引导式帮助)内容设计器所期望的 DOM 属性的名称,用于标识模型驱动应用窗体中的 UI 控件。
getResourceString 返回与指定 Web 资源关联的给定密钥的本地化字符串。
invokeProcessAction 根据指定参数调用操作。 这种方法还可用于调用由您的开发人员创建的自定义 API。
LookupObjects 打开查找控件以选择一个或多个项。
refreshParentGrid 刷新包含指定记录的父网格。
showProgressIndicator 显示包含指定消息的进度对话框。

您可能会在旧代码中遇到许多其他在此处未列出的方法,这些方法现在已弃用,因为它们已移至 Xrm.Navigation 命名空间。 如果您看到这些方法,则应更新代码以使用新的 Xrm.Navigation 方法。

Xrm.WebApi 对象

Xrm.WebApi 对象提供在客户端脚本中将 Web API 用于传统 CRUD 操作的属性和方法。 当您在脚本中使用 Xrm.WebAPI 时,操作将自动在当前应用用户的上下文中执行。 当应用处于联机和脱机状态时,均可使用 Web API(如果配置了脱机环境)。 命名空间包括一组特定的联机和脱机方法;但是,使用这些方法需要跟踪客户端状态。 如果您使用 Xrm.WebAPI、Xrm.WebAPI.createRecord,则 API 会代您确定应该使用联机还是脱机命名空间方法。

下表汇总了 Xrm.WebApi 对象中提供的方法。 有关详细信息,请参阅 Xrm.WebApi(客户端 API 引用)。

方法 描述
createRecord 创建表行。
deleteRecord 使用行的 ID 删除表行。
retrieveRecord 使用行的 ID 检索行。
retrieveMultipleRecords 检索与所提供的查询选项或 Fetch XML 匹配的表行集合。
updateRecord 更新表行。
isAvailableOffline 返回布尔值,该值指示表是否存在于用户的配置文件中且可在脱机模式下使用。
execute 运行单个操作、函数或 CRUD 操作。
executeMultiple 运行操作、功能或 CRUD 操作的集合。

使用 Xrm 对象的属性和方法,您可以自动执行业务流程并改进整体用户体验。