客户端脚本常见任务

已完成

客户端 API 对象模型广泛且丰富。 当您逐渐熟悉客户端脚本时，您会意识到可以使用许多 API 对象和方法来实施逻辑。 在本单元中，我们将了解您可以执行的一些常见任务以及用于完成这些任务的技术。

访问 Dataverse 列数据

Dataverse 列在对象模型中表示为属性对象。 您可以使用 formContext 对象的 getAttribute() 方法，快速查找窗体上存在的特定属性或所有属性。 每个属性对象都包含一些无论数据类型如何都可用的通用方法。 还有其他方法可用于指定属性数据类型（文本、数字、日期等）。

注意

此示例代码假定所使用的属性和控件已存在。 如果对象不可用，大多数方法将返回 null，并且在实践中应使用常规的防御性检查。

提示

客户端 API 方法返回的集合具有一些有用的方法，您可以使用这些方法来迭代浏览元素。 有关详细信息，请参阅模型驱动应用中的集合（客户端 API 引用）- Power Apps。

任务	示例
按名称访问	javascript var nameAttribute = formContext.getAttribute("name"); 将 Account Name 列的属性分配到 nameAttribute 变量。 如果窗体上不存在属性，getAttribute 方法将返回 null 值。
访问所有属性	javascript var allAttributes = formContext.getAttribute(); 将 formContext.data.entity.attributes 集合中所有属性的数组分配到 allAttributes 变量。

使用属性

任务	示例
获取属性的值	javascript var nameValue = formContext.getAttribute("name").getValue(); 将 Account Name 列的值分配到 nameValue 变量。
设置属性的值	javascript formContext.getAttribute("name").setValue("new name"); 将 Account Name 列的值设置为“new name”。
获取 OptionSet 属性（Dataverse 选项列）中当前选定的选项对象	javascript var addressTypeOption = formContext.getAttribute("address1_addresstypecode").getSelectedOption(); 将 Address Type 列中的选定选项分配到 addressTypeOption 变量。
确定自窗体打开后，用户界面中的属性值是否已更改	javascript var isNameChanged = formContext.getAttribute("name").getIsDirty(); 分配一个布尔值，指示 Account Name 列值是否已更改并将值分配到 isNameChanged 变量。
更改数据在列中是否为必需才能保存记录	javascript formContext.getAttribute("creditlimit").setRequiredLevel("required"); 使 Credit Limit 列为必需。 javascript formContext.getAttribute("creditlimit").setRequiredLevel("none"); 使 Credit Limit 列为可选。
确定在保存记录时是否将提交属性中的数据	javascript var nameSubmitMode = formContext.getAttribute("name").getSubmitMode(); nameSubmitMode 变量值将为 always、never 或 dirty 文本以表示 Account Name 列的 submitMode。
控制在保存记录时是否将保存属性中的数据	javascript formContext.getAttribute("name").setSubmitMode("always"); 本示例将强制 Account Name 列值始终保存，即使它未更改。
将列级别安全性应用于属性后，确定用户是否具有对属性执行创建、读取或更新操作的特权。	javascript var canUpdateNameAttribute = formContext.getAttribute("name").getUserPrivilege().canUpdate; 分配一个布尔值，表示用户将 Account Name 列更新到 canUpdateNameAttribute 变量的特权。

访问窗体控件

任务	示例
访问特定属性的所有控件	javascript var nameControls = formContext.getAttribute("name").controls.get(); 将 name 属性的所有控件的数组分配到 nameControls 变量。 大多数属性都由一个控件表示，但如果已将列多次添加到窗体，则可能存在多个控件。
按名称访问控件	javascript var nameControl = formContext.getControl("name"); 添加到列的窗体的第一个控件将具有与该列相同的名称。 每个其他控件名称都将在该名称后附加一个索引号。 例如，名称列的三个控件名称将分别为 name、name1 和 name2。
访问所有控件	javascript var allControls = formContext.getControl(); 将 formContext.ui.controls 集合中所有控件的数组分配到 allControls 变量。

使用窗体控件

与属性对象类似，控件对象具有一组通用方法，无论类型如何。 它们还具有基于控件类型的专用方法。

任务	示例
确定控件是否可见	javascript var isNameVisible = formContext.getControl("name").getVisible(); 将布尔值分配到 isNameVisible 变量，以表示 Account Name 列是否可见。
隐藏或显示控件	javascript formContext.getControl("name").setVisible(false); 隐藏 Account Name 列。
获取对控件的属性的引用	javascript var nameAttribute = formContext.getControl("name").getAttribute(); 将 Account Name 列的控件的属性分配到 nameAttribute 变量。
禁用或启用属性的所有控件	javascript formContext.getAttribute("name").controls.forEach(function (control, index) { control.setDisabled(true); }); 请记住，任何属性都可能具有多个控件。
更改控件的标签	javascript formContext.getControl("name").setLabel("Company Name"); 将 Account Name 列的标签设置为文本 Company Name。
获取控件的父级	javascript var parentSection = formContext.getControl("name").getParent(); 将 Account Name 列的父级控件分配到 parentSection 变量。
对控件设置焦点	javascript formContext.getControl("name").setFocus(); 将当前输入焦点设置为 Account Name 列。

使用选项卡和部分

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

任务	示例
显示或隐藏选项卡	javascript formContext.ui.tabs.get("general").setVisible(false); 隐藏常规选项卡。
更改选项卡的标签	javascript formContext.ui.tabs.get("general").setLabel("Major"); 将 general 选项卡的标签设置为文本 Major。
显示或隐藏部分	javascript formContext.getControl("industrycode").getParent().setVisible(false); 隐藏包含 Industry Code 列的部分。

使用实体数据

下表包含您可以用于获取有关当前记录的信息的方法。

任务	示例
获取当前记录的 ID	javascript var recordId = formContext.data.entity.getId(); 将当前记录唯一标识符分配到 recordId 变量。 如果窗体已打开以创建新记录，将返回 null 值。
保存当前记录	javascript formContext.data.entity.save(); 使用 saveandclose 或 saveandnew，通过使用保存并关闭或保存并新建执行等效操作。
确定是否更改当前记录中的任何数据。	javascript var isDirty = formContext.data.entity.getIsDirty(); 分配一个布尔值，指示窗体上的任何列值是否已更改为 isDirty 变量。