创建应用特定的操作

学习目标

  • 创建带参数的操作。

应用特定的操作

在 SAP Fiori elements 中,你可以使用 Delete 和 Create 等通用操作。如果你的应用需要超出此范围的操作,你可以创建自己的应用特定操作。

应用特定的操作可以是基于注释的操作,也可以是自定义操作。

基于注释的操作

基于注释的操作是使用相应的注释创建的。它们可用于以下情况:

  • 需要用户确认,例如对于关键操作。会打开一个弹出对话框,用户必须确认该操作。有关更多信息,请参阅 Adding Confirmation Popovers for Actions 。

  • 需要额外的用户输入。某些值可能已经预先填写。

  • 该操作通过 OData 服务触发后端调用,例如 Approve 。

  • 该操作触发导航,例如导航到另一个应用。有关更多信息,请参阅 Configuring Navigation.

自定义操作

如果你需要的操作无法由基于注释的操作覆盖,则可以创建自定义操作。它们使用需要在 manifest.json 文件中注册的扩展点来创建。有关更多信息,请参阅 Adding Custom Actions Using Extension Points。

基于注释的操作的可见性

你可以使用 @Core.OperationAvailable 注释更改基于注释的操作的可见性。

该注释既可以具有静态值(布尔值 true 或 false),也可以具有动态值(指向某个属性的路径)。如果该值是静态的且设置为 true,则该操作将始终可用,无论选择哪个条目。如果该值是动态的,则可以根据特定条件动态启用或禁用该操作。

请看以下 CAP CDS 注释:

actions {
deductDiscount @(
Core.OperationAvailable : { $edmJson: { $Eq: [{ $Path: 'in/TravelStatus_code'}, 'O']}}
);
}

在此示例中,操作 deductDiscount 仅对 TravelStatus 为 'O'(open)的条目可用。注释 Core.OperationAvailable 的值是包含在 { $edmJson: { … }} 中的动态表达式。

有关 OData 版本 4 中动态表达式的更多信息,请参阅 OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01 (oasis-open.org)。

CDS 编译器会将该表达式转换为相应的 XML 代码。上述注释被转换为以下 OData 表示形式:

<Annotations Target="TravelService.deductDiscount(TravelService.Travel)">
<Annotation Term="Core.OperationAvailable">
<Eq>
<Path>in/TravelStatus_code</Path>
<String>O</String>
</Eq>
</Annotation>
</Annotations>

有关 CAP CDS 和动态表达式的更多信息,请参阅:Dynamic Expressions。

创建带必需参数的应用程序特定操作

除了所有 SAP Fiori elements 应用通用的通用操作外,你还可以创建应用特定的操作。

在本练习中,你将针对 Travels 表创建一个基于注释的操作。它将从预订费和总价中扣除折扣。该操作将具有一个必需参数:折扣百分比,默认值为 5。该操作将被添加到列表报表的表工具栏中。

任务流程

在本练习中,你将首先创建 deductDiscount 操作并实现它。该操作将仅适用于旅行状态为 Open 的旅行。然后,你将使用 Page Editor 将该操作添加到列表报表的表工具栏中。最后,你将测试新创建的操作。

前提条件

你已完成单元 Examining Actions Available on the List Report(课程:Applying Generic Actions Provided by SAP Fiori Elements)中的练习 Make the Delete Action Unavailable for Accepted and Canceled Travels。或者,你可以签出其解决方案分支:solution/make-delete-action-unavailable-for-accepted-travels。

观看模拟并执行步骤

本练习包含一个展示所有步骤的模拟。你可以使用自己的试用账户跟随该模拟操作。

Exercise:Start Exercise(SAP 官方交互式练习)

步骤

  1. 创建操作并实现它。

  2. 在 SAP Business Application Studio 中打开 travel-service.cds 文件。

  3. 添加新操作 deductDiscount 的定义。请注意,它有一个必需参数,其默认值为百分之五。 将以下代码片段添加到 travel-service.cds 文件的 actions 部分:

action deductDiscount(@(UI.ParameterDefaultValue : 5)percent: Percentage not null @mandatory ) returns Travel;
  1. 打开 travel-service.js 文件以实现该操作。如果 Travel Status 不是 'A'(Accepted)且 Booking Fee 不是 null,该操作将同时更新 TotalPrice 和 BookingFee 属性。 将以下代码片段添加到 srv/travel-service.js 文件:

this.on ('deductDiscount', async req => {
let discount = req.data.percent / 100
let succeeded = await UPDATE (req.subject)
.where `TravelStatus_code != 'A'`
.and `BookingFee is not null`
.with (`
TotalPrice = round (TotalPrice - BookingFee * ${discount}, 3),
BookingFee = round (BookingFee - BookingFee * ${discount}, 3)
`)
if (!succeeded) { //> let's find out why...
let travel = await SELECT.one `TravelID as ID, TravelStatus_code as status, BookingFee` .from (req.subject)
if (!travel) throw req.reject (404, `Travel "${travel.ID}" does not exist; may have been deleted meanwhile.`)
if (travel.status === 'A') req.reject (400, `Travel "${travel.ID}" has been approved already.`)
if (travel.BookingFee == null) throw req.reject (404, `No discount possible, as travel "${travel.ID}" does not yet have a booking fee added.`)
} else {
return this.read(req.subject)
}
})
  1. 将该操作的可用性限制为旅行状态为 Open 的旅行。

  2. 打开 field-control.cds 文件,并将 @Core.OperationAvailable 注释添加到 deductDiscount 操作。 将以下代码片段添加到 app/travel_processor/field-control.cds 文件:

deductDiscount @(
Core.OperationAvailable : { $edmJson: { $Eq: [{ $Path: 'in/TravelStatus_code'}, 'O']}}
);
  1. 现在,仅当 Travel Status 为 'O'(Open)时该操作才可用。

  2. 打开 Page Editor 以添加更改。

  3. 转到 List Report > Toolbar,并将 TravelService.deductDiscount 操作添加到表工具栏。

  4. 选择你刚刚添加的操作。请注意,你可以在右侧窗格中更改其设置。

  5. 选择 Label 注释,以在 i18n.properties 文件中生成文本键。

  6. 返回应用以检查你新创建的操作。

  7. 操作 Deduct Discount 现在出现在表工具栏中。

  8. 选择旅行状态为 Accepted 的旅行。请注意,该操作不可用。

  9. 现在选择旅行状态为 Open 的旅行。该操作现在可用,并且可以应用。

  10. 将 Deduct Discount 操作应用于所选旅行。Booking Fee 和 Total Price 现在都已按指定金额减少。

结果

在本课中,你已向表工具栏添加了一个应用特定的操作,并限制了该操作对特定条目的可用性。

注意

  • 你可以在 GitHub 上找到本练习的解决方案。

  • 解决方案分支是 solution/create-action-with-a-mandatory-parameter 。

  • 你可以在 GitHub 上找到该分支与上一个分支直接比较的链接。

后续步骤

有关更多信息,请参阅 Actions in the List Report。