创建应用特定的操作

学习目标

创建带参数的操作。

应用特定的操作

在 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 官方交互式练习）

步骤

创建操作并实现它。
在 SAP Business Application Studio 中打开 travel-service.cds 文件。
添加新操作 deductDiscount 的定义。请注意，它有一个必需参数，其默认值为百分之五。将以下代码片段添加到 travel-service.cds 文件的 actions 部分：

action deductDiscount(@(UI.ParameterDefaultValue : 5)percent: Percentage not null @mandatory ) returns Travel;

打开 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)
}
})

将该操作的可用性限制为旅行状态为 Open 的旅行。
打开 field-control.cds 文件，并将 @Core.OperationAvailable 注释添加到 deductDiscount 操作。将以下代码片段添加到 app/travel_processor/field-control.cds 文件：

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

现在，仅当 Travel Status 为 'O'（Open）时该操作才可用。
打开 Page Editor 以添加更改。
转到 List Report > Toolbar，并将 TravelService.deductDiscount 操作添加到表工具栏。
选择你刚刚添加的操作。请注意，你可以在右侧窗格中更改其设置。
选择 Label 注释，以在 i18n.properties 文件中生成文本键。
返回应用以检查你新创建的操作。
操作 Deduct Discount 现在出现在表工具栏中。
选择旅行状态为 Accepted 的旅行。请注意，该操作不可用。
现在选择旅行状态为 Open 的旅行。该操作现在可用，并且可以应用。
将 Deduct Discount 操作应用于所选旅行。Booking Fee 和 Total Price 现在都已按指定金额减少。

结果

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

注意

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

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

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

后续步骤

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