有关使用客户端 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 对象的属性和方法,您可以自动执行业务流程并改进整体用户体验。