预定义 JavaScript 函数

CA Service Catalog 提供了若干选项，用于在表单中执行窗口项的自动化任务，其中包括报告数据对象、JavaScript 表达式和 JavaScript 函数。 本主题列出了预定义的 JavaScript 函数，并概述了如何选择使用它们在窗口项中实现任务的自动化。

为若干预定义 JavaScript 函数中使用的操作数指定值要遵循以下方针。 对于大多数函数而言，以下列表中的前两个操作数是必选的，其余操作数是可选的。 验证单个函数的语法，以确定哪些操作数适用于该函数。

• 对于 formId，请指定您想运行函数的表单的 _id 属性值。
• 对于 _id，请在想运行函数的表单中指定该元素的 _id 属性值。
• 对于名称、值和索引，请指定该元素的这些属性值（函数正在该元素上运行）。
• 如适用，还为特定函数提到了附加的操作数。 例如，索引属性仅适用于某些元素，如选择组。

_.serviceoption.status( )

返回当前表单所属的行项目的状态。 使用该函数可根据行项目的状态动态指定表单属性。 例如，要在某些表单窗口项的行状态为“已完成”时隐藏这些窗口项，请将其“隐藏”属性设置为“_.serviceoption.status() == 200”。

注意：还可以使用该函数来隐藏或禁用服务选项元素。 要执行此操作，请在隐藏或禁用的文本框中使用该函数。

该函数对于“暂停”和“恢复”状态也尤为有用。 您可以为两者在文本消息中给出原因。

注意：该函数不带任何参数。

ca_fdDoFieldLookup(fieldId, reportId)，

运行报告数据对象，将其关联到查找窗口项，并将返回的数据复制到表单上的匹配窗口项中。 您可以使用这些操作以便基于用户在报告数据对象中的输入填充窗口项。

对于 fieldId，请指定查找字段的 _id 属性值。

对于 reportId，请指定您较早创建的数据对象的值。

ca_reportQuery（reportId、变量、onSuccess、onFailure）

运行报告数据对象（数据对象），该对象会针对您指定的数据查询数据源（如 MDB）并返回结果。

• 对于 reportId，请指定想要查询的数据对象。
• 对于变量，指定具有变量名称和值的 JavaScript 映射。 示例包括 {“var1”:”foo”,”var2”:”bar”,”var3”:_.user.id}。 这些变量与您在报告数据对象中查询到的相匹配。
• 对于 onSuccess，当查询成功返回时，请指定要运行的 JavaScript 函数。 onSuccess 函数必须接受一个操作数。 该操作数是使用一组映射设置的，每个代表一行，由查询返回。
• 对于 onFailure，请指定调用失败时要运行的 JavaScript 函数。

可以基于报告数据对象和 JavaScript 函数预填充窗口项。

ca_fdValidateCC(credit card number, credit card type)

验证用户在您创建的表单中输入的信用卡号码的格式。

ca_fdShowField(formId, _id)

适用于单个窗口项。

查找指定的表单 (formId) 和窗口项 (_id)。 如果该窗口项尚不可见，还要使其可见。

ca_fdShowFields(formId, _ids)

适用于多个窗口项。

查找指定的表单 (formId) 和窗口项 (_ids) 如果这些窗口项尚不可见，还要使其可见。

第二个参数是由表单上多个窗口项的 _ids 组成的数组，如 ca_fdHideFields(formId, _ids) 的示例中所示。

ca_fdHideField(formId, _id)

适用于单个窗口项。

查找指定的表单 (formId) 和窗口项 (_id)。 如果该窗口项尚未隐藏，还要将其隐藏。

ca_fdHideFields(formId, _ids)

适用于多个窗口项。

查找指定的表单 (formId) 和窗口项 (_ids)。 如果这些窗口项尚未隐藏，还要将其隐藏。

第二个参数是由表单上多个窗口项的 _id 组成的数组。 例如，您要在表单上隐藏“名”和“姓”窗口项。 此外，表单的 _id 是 name_form，两个窗口项的 _id 值分别是 first_name 和 last_name。 在这种情况下，请使用以下代码：

ca_fdHideFields("name_form", ["first_name","last_name"]

ca_fdDisableField(formId, _id)

适用于单个窗口项。

查找指定的表单 (formId) 和窗口项 (_id)。 如果尚未禁用该窗口项，还要将其禁用。

ca_fdDisableFields(formId, _ids)

适用于多个窗口项。

查找指定的表单 (formId) 和窗口项 (_ids)。 如果尚未禁用这些窗口项，还要将其禁用。

第二个参数是由表单上多个窗口项的 _ids 组成的数组，如 ca_fdHideFields(formId, _ids) 的示例中所示。

ca_fdEnableField(formId, _id)

适用于单个窗口项。

查找指定的表单 (formId) 和窗口项 (_id)。 如果尚未启用该窗口项，还要将其启用。

ca_fdEnableFields(formId, _ids)

适用于多个窗口项。

查找指定的表单 (formId) 和窗口项 (_ids)。 如果尚未启用这些窗口项，还要将其启用。

第二个参数是由表单上多个窗口项的 _ids 组成的数组，如 ca_fdHideFields(formId, _ids) 的示例中所示。

ca_fdSelectOption(formId, _id, name, value) 和 ca_fdSelectOptionByIndex(formId, _id, index)

可以使用其中任一函数通过编程方式在选择框中选择值。 这些函数的效果相同，只是调用方式不同：

• ca_fdSelectOption 从具有指定 _id 属性的选择窗口项中选择具有指定名称和值的选项。
• ca_fdSelectOptionByIndex 从具有指定 _id 属性的选择窗口项中选择具有指定索引值的选项。

考虑下列示例：

示例 1

此示例选择选择框中的第一个选项。 该示例使用以下值：

• 表单的 _id 属性：form_id
• 选择框的 _id 属性：memory_select

  ca_fdSelectOption(‘form_id’, ‘memory_select’, 1)：
  

示例 2

此示例选择当前表单的选择框中的第一个选项。 该示例使用以下值：

• 表单的 _id 属性：ca_fd.formId
• 选择框的 _id 属性：memory_select

  ca_fdSelectOption(ca_fd.formId, ‘memory_select’, 1)：
  

如果找不到指定的选择框，则忽略调用，并且不报告任何错误。

示例 3

可以用选项的显式值改写前面的示例，如下所示：

ca_fdSelectOption(‘form_id’, ‘memory_select’, ‘option1’, ‘option1_value’), ca_fdSelectOption(ca_fd.formId, ‘memory_select’, ‘option1’, ‘option1_value’)：

option1

指定选项在表单设计器树中显示时的名称。 此选项的值为 option1_value。

ca_fdUnselectOption(formId, _id, name, value)

取消选择具有相应 _id 属性的选择窗口项中具有指定名称和值的选项。

ca_fdUnselectOptionByIndex(formId, _id, index)

取消选择具有相应 _id 属性的选择窗口项中位于相应索引位置的选项。

ca_fdUnselectAllOptions(formId, _id)

取消选择具有相应 _id 属性的选择窗口项中的所有选项。

ca_fdGetSelectedOptions(formId, _id)

返回表示选定选项索引的 ans 整数数组。

ca_fdGetSelectedOptionValues (formId, _id)

返回一个字符串数组，表示选定选项的值。 按照以下方式选择第一个选项值：

ca_fdGetSelectedOptionValues(formId, _id)[0]

通过将 0 更改为 1 选择第二个选项值；通过将 1 更改为 2 选择第三个选项值，以此类推。

该函数对于使用用户输入预填充选择框尤为有用。

ca_fdSelectRadio(formId, name, _id)

在具有相应名称属性的单选按钮组中，选择具有相应 _id 的单选按钮。

ca_fdIsSelectRadio (formId, name, _id)

返回是否选中了指示的单选按钮。

ca_fdSelectCheckBox(formId,_id)

选择具有相应 _id 属性的复选框。

ca_fdUnselectCheckBox(formId, _id)

清除具有相应 _id 属性的复选框。

ca_fdIsSelectedCheckBox(formId,_id)

返回是否选中了选定的复选框。

ca_fdSetDateFieldValue(formId, _id, date) 和相关函数

为具有相应 _id 属性的指定日期窗口项设定值。 该函数中名为 date 的参数可取 Null、String 或 Long 整数值。

要清除窗口项的值，请使用空字符串和 null。

采用为日期/时间窗口项（表单的元素）指定的格式指定非空字符串，如下所示：

• 如果日期/时间窗口项的时间部分被隐藏，则仅采用日期格式指定字符串。 采用日期/时间窗口项的格式属性或业务单位的“日期”格式。
• 如果日期/时间窗口项的时间部分可见，则采用该窗口项中指定的日期和时间的格式指定字符串。

在上述两种情况下，均用空格分隔多个字符串。

用于设置日期的相关 JavaScript 函数如下所示。 前面针对 ca_fdSetDateFieldValue(formId, _id, date) 函数的文本也适用于这些函数。

• ca_fdSetDateFieldMinValue(formId, _id, date) - 设置日期的最小值。
• ca_fdSetDateFieldMaxValue(formId, _id, date) - 设置日期的最大值。

此外，对于所有 ca_fdSetDateField*JavaScript 函数，可用自“时间纪元”以来经过的毫秒数设置日期。时间纪元是标准基础时间，即格林威治时间 1970 年 1 月 1 日午夜 (00:00:00)。 有关以此方式设置日期的详细信息，请参阅标准 Java 编程参考，例如，Oracle 网站 oracle.com。

ca_fdGetDateFieldValue(formId, _id, date) 和相关函数

获取指定日期窗口项的值，该值是采用日期窗口项的指定格式的字符串。

针对前一个函数 (ca_fdSetDateFieldValue(formId, _id, date)) 说明的日期/时间窗口项的信息同样适用于该函数。

用于获取日期的相关 JavaScript 函数如下所示。 前面针对 ca_fdGetDateFieldValue(formId, _id, date) 函数的文本也适用于这些函数。

• ca_fdGetDateFieldValueInMillis(formId, _id, date) - 获取日期的值（毫秒）。
• ca_fdGetDateFieldMinValue(formId, _id, date) - 获取日期的最小值。
• ca_fdGetDateFieldMinValueInMillis(formId, _id, date) - 获取日期的最小值（毫秒）。
• ca_fdGetDateFieldMaxValue(formId, _id, date) - 获取日期的最大值。
• ca_fdGetDateFieldMaxValueInMillis(formId, _id, date) - 获取日期的最大值（毫秒）。

此外，对于所有 ca_fdGetDateField*JavaScript 函数，可用自“时间纪元”以来经过的毫秒数获取日期。时间纪元是标准基础时间，即格林威治时间 1970 年 1 月 1 日午夜 (00:00:00)。 有关以此方式获取日期的详细信息，请参阅标准 Java 编程参考，例如，Oracle 网站 oracle.com。

ca_fdSetTextFieldValue(formId, _id, text)

设置具有相应 _id 属性的文本字段的文本，该属性可以是文本字段和文本区域。

ca_fdGetTextFieldValue(formId, _id)

获取具有相应 _id 属性的文本字段的文本，该属性可以是文本字段和文本区域。

ca_fdFetchSelectData(formId,_id)

使得带有指定 _id 的选择框再次获取报告数据对象。 在报告数据对象考虑用户输入时，该函数特别有用。 作为一项最佳实践，请在该输入更改时调用该函数，以帮助确保选择框显示正确数据。

该函数对于使用用户输入预填充选择框也特别有用。

下列函数仅用于系统表单：

• custom_onPriorityChange(newPriority)
• custom_onDateRequiredChange(newDateRequired)
• custom_onRequestedForChange(type, id, name, shippingAddress)