使用数据类型

学习目标

  • 使用数据类型来格式化和校验数据

格式化、解析和校验数据

观看视频以了解格式化程序（formatter）和数据类型。

视频：本节含 SAP 官方视频（视频 ID 1_hjgkepei），需在 learning.sap.com 在线观看。

在本课中，我们将首先讨论数据类型。格式化程序将在下一课中介绍。

简单类型

如前所述，数据类型允许你格式化模型数据以便在 UI 上显示，同时也可以解析和校验用户输入。

当前可用的数据类型都继承自 sap.ui.model.SimpleType 类。有关所有这些简单类型的完整列表，请参见 sap.ui.model.type 命名空间下的 API Reference。

在本培训课程中，将通过示例简要介绍以下三种简单类型：sap.ui.model.type.Integer、sap.ui.model.type.Date 和 sap.ui.model.type.Currency。

除了 SAP 提供的简单类型外，你还可以定义自己的自定义数据类型。为此，必须创建 SimpleType 的子类。在该子类中，为 SimpleType 类的 formatValue、parseValue 和 validateValue 方法提供自定义实现。

可以通过简单类型的构造函数传递以下参数：

  • formatOptions : 格式选项定义值应如何在 UI 上格式化和显示。

  • constraints : 约束定义在 UI 上输入的值应具有何种形式。输入的值将根据指定的约束进行校验。

可以在数据绑定中指定简单类型，以定义模型数据的数据类型。在 XML 视图中为此使用复杂绑定语法。

如果输入的值无法成功解析或不在定义的约束范围内，则会引发异常。这会导致输入的值不会被传输到模型。

数据类型 Integer

Integer 数据类型支持 maximum 和 minimum 校验约束。支持的格式选项列在 API Reference 中，参见类 sap.ui.core.format.NumberFormat。

Integer 数据类型表示一个整数值。

在图中 The Integer Data Type 的示例中，Input UI 元素通过复杂绑定语法绑定到名为 customer 的模型中的 Discount 属性。绑定中的 type 属性指定了 sap.ui.model.type.Integer 数据类型，constraints 属性定义了只允许 0 到 100 之间的值。因此，如果用户输入负值或大于 100 的值，该值不会被传输到模型。

同样，无法解析为整数的输入值（例如 "abc"）也不会被传输到模型。

数据类型 Date

Date 数据类型表示不带时间的日期。

该类型将模型中的给定值转换为格式化后的日期字符串，反之亦然。

代码片段显示了 带有 的 绑定。模型数据包含航班日期，UI 显示格式化后的日期，例如 Feb 27, 2024 和 Feb 28, 2024。

在图中 The Date Data Type 所示的示例中，模型数据中的 _Bookings 数组通过 UI 上的表格输出。数组中的每个预订都包含一个 FlightDate 属性，该属性在表格中显示为单独的列。该表列的绑定使用了与上面相同的复杂绑定语法。

绑定中的 type 属性指定了数据类型 sap.ui.model.type.Date。通过 formatOptions，使用 source 属性中提供的模式指定模型数据中航班日期的数据格式。这样的模式也可用于定义输出格式。不过，更推荐使用样式（"short"、"medium"、"long" 或 "full"），因为它会自动使用与区域相关的日期模式。

Date 类型支持以下校验约束：

  • maximum （要求日期以 source 模式格式表示）

  • minimum （要求日期以 source 模式格式表示）

有关更多信息，请参见 sap.ui.model.type.Date 的 API Reference。

数据类型 Currency

Currency 数据类型是一种复合类型。它由 "amount"（类型为 number 或 string）和 "currency"（类型为 string）两部分组成。

_Bookings 数组的代码片段，如文中所述。

在图中 The Currency Data Type 所示的示例中，模型数据中的 _Bookings 数组通过 UI 上的表格输出。数组中的每个预订都有两个属性 ForeignCurrencyPayment 和 ForeignCurrency。一个 ObjectNumber UI 元素将这两个属性的值在一个表列中显示为带币种的金额。

对于 number 属性的绑定，使用复杂绑定语法将 sap.ui.model.type.Currency 指定为模型数据的类型。

绑定中还指定的 parts 数组包含 Currency 数据类型所需两个值（金额和币种）的路径。

此外，格式化选项 showMeasure 被设置为 false。这会隐藏 number 属性中的币种代码，因为它会作为单独的属性 unit 传递给 ObjectNumber 控件。

因此，Currency 数据类型会基于币种代码对 ForeignCurrencyPayment 模型属性进行格式化。例如，以欧元 (EUR) 表示的货币金额会显示 2 位小数，而以日元 (JPY) 表示的金额则没有小数位。

有关更多信息，请参见 sap.ui.model.type.Currency 的 API Reference。

校验处理

如果你按 Enter 或将焦点移到另一个 UI 控件，SAPUI5 会执行属于相应数据类型的解析和校验函数。

如果由于用户输入不正确而发生解析或校验异常，这些错误不会自动显示在 UI 上。

你可以使用消息管理器（message manager）将这些错误消息报告回给用户。为此，必须将相应的 UI 元素注册到消息管理器。有几种方法可以做到这一点。

你可以通过 manifest.json 应用描述符的 sap.ui5 部分中的消息管理器启用自动消息生成，也可以在实例化组件时将其作为参数启用。你还可以使用 registerObject 方法将控件注册到消息管理器，从而为单个控件启用它。

包含 handleValidation 代码的屏幕截图，如以下文本所述。

在图中 Validation Handling Using the Message Manager 所示的示例中，应用描述符中的 handleValidation 属性用于为组件启用由消息管理器进行的校验处理。

因此，组件中使用的所有 UI 元素的解析和校验错误都由消息管理器处理。也就是说，基于用户输入生成的任何解析和校验错误消息都会被消息管理器接收，消息管理器再将该错误消息传回正确的 UI 元素进行显示。

出错的字段具有红色边框。错误消息本身仅在字段获得焦点时显示。

使用数据类型

业务场景

在本练习中，你将向应用程序添加校验和格式化。为此，你首先将使用应用描述符为输入校验启用自动消息创建。然后，你将把 Simple Types 添加到你已创建的一些数据绑定中，以校验或格式化数据。*模板：*Git Repository: https://github.com/SAP-samples/sapui5-development-learning-journey.git, Branch: **sol/13_element_binding***参考答案：*Git Repository: https://github.com/SAP-samples/sapui5-development-learning-journey.git, Branch: sol/14_data_types

任务 1：为组件启用由消息管理器进行的校验处理

步骤

  1. 在编辑器中打开 *webapp* 文件夹中的 *manifest.json* 应用描述符。

  2. 在 sap.ui5 命名空间中的某处添加以下属性，以便为组件启用由消息管理器进行的校验处理：

"handleValidation": true

结果

sap.ui5 命名空间现在应类似于以下内容：

manifest.json 文件，突出显示了 handleValidation 函数。

任务 2：使用 Simple Types 校验和格式化应用程序数据

步骤

  1. 在编辑器中打开 *webapp/view* 文件夹中的 *Overview.view.xml* 文件。

  2. 按如下方式调整表单中 Discount 输入元素的数据绑定： | Old | New | | --- | --- | | <Input value="{customer>/Discount}"/> | <Input value="{ path: 'customer>/Discount', type: 'sap.ui.model.type.Integer', constraints: {minimum: 0, maximum: 100} }"/> |

注意

就输入校验而言，调整后的数据绑定会使消息管理器在以下情况下显示错误：

  • 如果用户输入无法解析为整数。- 如果输入的整数值不在 0 到 100 之间。

结果

表单现在应如下所示： Overview.view.xml 文件，突出显示了 Input 标签。 3. 按如下方式调整预订表中 Flight Date 列的数据绑定：

Old

New

<ObjectIdentifier title="{FlightDate}"/>

`

注意

调整后的数据绑定会将 FlightDate 模型属性的内容转换为格式化后的日期字符串。在 webapp/model 文件夹的 data.json 文件中，航班日期存储为字符串，例如 "2024-02-27"。通过该数据绑定，它会转换为格式 "Feb 27, 2024"。

结果

预订表现在应如下所示： Overview.view.xml 文件，突出显示了 ObjectIdentifier 标签。 4. 按如下方式调整预订表中 Foreign Currency Payment 列的数据绑定：

Old

New

<ObjectNumber number="{ForeignCurrencyPayment}" unit="{ForeignCurrency}"/>

<ObjectNumber number="{ parts: \[ {path: 'ForeignCurrencyPayment'}, {path: 'ForeignCurrency'} \], type: 'sap.ui.model.type.Currency', formatOptions: {showMeasure: false} }" unit="{ForeignCurrency}"/>

注意

添加的 Currency 数据类型会基于币种代码对 ForeignCurrencyPayment 模型属性进行格式化。例如，以欧元 (EUR) 表示的货币金额会显示 2 位小数，而以日元 (JPY) 表示的金额则没有小数位。

此外，格式化选项 showMeasure 被设置为 false。这会隐藏 number 属性中的币种代码，因为它会作为单独的属性 unit 传递给 ObjectNumber 控件。

结果

预订表现在应如下所示： Overview.view.xml 文件，突出显示了 ObjectNumber 标签。 5. 通过从 SAP Business Application Studio 启动应用程序来进行测试运行。 确保应用程序中现在已具备上述校验和格式化功能。

  1. 右键单击你的 sapui5-development-learning-journey 项目中的任意子文件夹，然后在出现的上下文菜单中选择 Preview Application。

  2. 在出现的对话框中选择名为 start-noflp 的 npm 脚本。

  3. 在打开的应用程序中，检查组件是否按预期工作。