在 CDS 视图中使用 ABAP 注释

学习目标

  • 在 CDS 视图中使用 ABAP 注释。

  • 在 CDS 中使用可翻译文本。

CDS 视图的 ABAP 注释

SAP 注释是由 SAP 创建和提供的 CDS 注释。根据评估，我们区分两组 SAP 注释：ABAP 注释和框架特定注释。

ABAP 注释

ABAP 注释定义 CDS 对象的技术和语义属性。当激活 CDS 源代码中定义的对象或在 ABAP 运行时环境中使用该对象时，将对其进行评估。ABAP 注释可以修改访问 CDS 对象的 ABAP SQL 语句的行为。

框架特定注释

框架特定的注释定义了特定软件组件（例如 ODATA、UI、分析等）所需的 CDS 对象的技术和语义属性。它们由相应软件组件的框架使用合适的 API 进行评估，与激活和 ABAP 运行时环境无关。

根据范围，我们区分五组注释：

实体注释

CDS 视图和 CDS 视图实体的注释。放在 DEFINE VIEW 语句或 DEFINE VIEW ENTITY 语句的前面。

元素注释

CDS 视图的 SELECT 列表元素的注释。放在元素前面。

参数注释

CDS 视图参数的注释。置于参数前面。

扩展注释

CDS 视图扩展的注释。置于 EXTEND VIEW 语句或 DEFINE VIEW ENTITY 语句的前面。

函数注释

CDS 表函数的注释。放在 DEFINE TABLE FUNCTION 语句的前面。

CDS 视图实体的重要 ABAP 注释

对于 CDS 视图实体，存在以下重要的 ABAP 注释：

AbapCatalog.dataMaintenance

可用于限制 CDS 视图实体的数据预览。

ABAPCatalog.viewEnhancementCategory

指定如何使用 CDS 视图扩展扩展视图实体。可以在注释数组的方括号中指定逗号分隔的值列表。

AccessControl.authorizationCheck

定义使用 ABAP SQL 访问 CDS 视图时的隐式访问控制。

ObjectModel.usageType。

<...>

根据性能相关属性对 CDS 视图实体进行特征化。

AbapCatalog.entityBuffer.definitionAllowed

可用于启用或禁用 CDS 视图实体的表缓冲。

视图元素的 ABAP 注释

大多数语义注释都只是：要由基于 CDS 构建的框架评估的语义信息。

语义类别中只有几个注释，即 ABAP 注释。

在 CDS 视图实体中，必须使用注释 @Semantics.amount.currencyCode 将金额元素（预定义字典类型 CURR）链接到货币代码元素（预定义字典类型 CUKY）。同样，必须使用注释 @Semantics.quantity.unitOfMeasure 将数量元素（预定义字典类型 QUAN）链接到单位元素（预定义字典类型 UNIT）。如果没有这些注释，CDS 实体的用户将很难正确解释和处理这些字段中提供的值。

分组注释

可以对同一注释类别中的注释进行分组，使其显示为属于一体。在此示例中，存在类别 ObjectModel 中的三个注释。所有这些都属于子类别 ObjectModel.usageType。在下方代码示例中，您会发现一个以 @ObjectModel: 开头的组，后跟一对花括号。在括号中，通常有一个以逗号分隔的注释列表，不包括第一部分 (ObjectModel)。在我们的示例中，只有一个以 usageType: 开头的子组，其以逗号分隔的列表中有三个注释。

提示

如果您更喜欢此语法，可以在通过自动完成插入注释时将其设置为缺省值。在 ADT 菜单中，转到 窗口→首选项 。转到 ABAP 开发→编辑器→源代码编辑器→CDS→代码完整化 ，然后在插入 CDS 注释下选择结构化（带有所有括号的多行）。

可翻译文本的 ABAP 注释

以 EndUserText 开头的 ABAP 注释用于定义 CDS 对象的可翻译语义文本。

EndUserText.label 可用作视图注释或元素注释。值的长度限制为 60 个字符。

EndUserText.quickinfo 仅可用作元素注释。该值存储为字符串并且可以具有任意长度。

注意

当视图元素基于字典数据元素时，CDS 框架会从数据元素中维护的字段标签中派生标签和快速信息。对于此类字段，仅当要覆盖来自数据元素的文本时才需要文本注释。

活动注释视图

活动注释视图汇总 CDS 实体及其元素的语义信息。其中列出了数据定义中包含的所有实体和元素注释。还会列出从其他资源库对象派生（继承）的语义信息，例如字典表定义和数据元素。

要打开 活动注释 视图，请执行以下操作：

  1. 右键单击 数据定义 。（在编辑器窗口或项目 浏览器 中。）

  2. 选择 打开方式 → 活动注释 。

在 ABAP 透视图的默认配置中， 活动注释 视图显示在编辑器视图下方标签条的新标签中。

在上述 的示例中，可以看到 CDS 视图实体 Z00_R_Employee 的元素 AnnualSalary 具有标签*"年薪*" 未在 CDS 数据定义中定义。此标签派生自数据库表 Z00_EMPLOYEE 中的源字段（继承），并且源自键入表字段的数据元素 Z00_SALARY。

如何在 CDS 视图中使用 ABAP 注释

播放视频以了解如何在 CDS 视图中使用 ABAP 注释。

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

在数据定义中使用注释

您想要使用元数据丰富 CDS 视图实体。在第一步中，定义和维护整个视图和单个视图元素的 ABAP 注释。

模板：

  • /LRN/R_EMPLOYEE（数据定义）

解决方案：

  • /LRN/R_EMPLOYEE_ANN（数据定义）

任务 1: 复制模板（可选）

复制模板数据定义。如果您已完成上一练习，则可以跳过此任务并继续编辑数据定义 Z##_EMPLOYEE。

步骤

  1. 将 /LRN/R_EMPLOYEE 数据定义复制到您自己的包中的数据定义（建议名称：Z##_EMPLOYEE，其中 ## 代表组编号）。

  2. 在项目浏览器视图中，右键单击 /LRN/R_EMPLOYEE 数据定义以打开上下文菜单。

  3. 从上下文菜单中，选择复制 ....

  4. 在包字段中输入包的名称。在名称字段中，输入 CDS 视图实体的名称（Z##_Employee，其中 ## 代表组编号）。

  5. 调整描述，然后选择下一步。

  6. 确认传输请求并选择完成。

  7. 激活复制。

  8. 按 Ctrl + F3 激活数据定义。

任务 2: 维护视图注释

在数据定义中，维护视图注释。添加可用于限制 CDS 视图实体的数据预览以及调整 ObjectModel.usageType 注释值的注释。

步骤

  1. 在数据定义开始时，使用代码完整化添加带有其默认值的注释 @ABAPCatalog.dataMaintenance。

  2. 将光标置于第一个代码行的开头，然后按**回车**插入新的空行。

  3. 在空行中，输入 @A 并按 Ctrl + Space 调用代码完成。

  4. 从建议列表中选择 @ABAPCatalog: { } （注释。

  5. 输入句号 (.) 并再次按 Ctrl + 空格。

  6. 选择 dataMaintenance: #RESTRICTED（注释）。

  7. 对以 @ABAPCatalog 开头的实体注释进行分组。

提示

您可以使用@ObjectModel.usageType 注释组的语法作为蓝图。

  1. 如下调整代码：

// @AbapCatalog.dataMaintenance: #RESTRICTED
// @AbapCatalog.viewEnhancementCategory: [#NONE]
@AbapCatalog: {
dataMaintenance: #RESTRICTED,
viewEnhancementCategory: [#NONE]
}
@AccessControl.authorizationCheck: #NOT_REQUIRED

  1. 显示 @ObjectModel.usageType 注释的文档并维护值。

注意

应确保注释值适合员工数据数据库表的技术表设置。

  1. 将光标置于 @ObjectModel上，然后按 F1 打开 ABAP 语言帮助。

  2. 在编辑器下方打开的 ABAP 语言帮助视图中，选择*@ObjectModel、CDS 视图注释、视图实体*。

  3. 对于 serviceQuality 注释，选择 #D，因为视图不支持事务处理。

  4. 对于 sizeCategory 注释，选择 #M，因为我们希望数据集少于 100,000 个。

  5. 对于 dataClass 注释，选择 #MASTER，因为员工数据是主数据。

任务 3: 维护元素注释

在数据定义中，添加必需元素注释以建立年薪和货币代码之间的链接。使用活动注释视图分析派生自数据元素的元素标签，并为 CurrencyCode 元素提供备选标签。

步骤

  1. 在元素清单中，取消注释 AnnualSalary 元素和 CurrencyCode 元素。

  2. 选择两个代码行，然后按 Ctrl + Shift + < 从每行的开头移除注释符号。

  3. 添加必填元素注释，将 AnnualSalary 元素标识为金额，并将其链接到 CurrencyCode 元素。

注意

您可能需要在代码完整化支持下手动添加此注释。编写时，数据定义编辑器不提供此错误的快速修复。（使用数据库表定义编辑器。）

  1. 如下调整代码：

department_id         as DepartmentId,
@Semantics.amount.currencyCode: 'CurrencyCode'
annual_salary         as AnnualSalary,
currency_code         as CurrencyCode,

  1. 打开活动注释视图，并分析不同视图元素的 EndUserText.Label 注释的值。

  2. 右键单击数据定义源代码中的任意位置，然后选择打开方式→活动注释。

结果

激活的注释 视图在编辑器视图下方显示为新标签。最终用户文本的源在 来源数据类型 列中列出。 4. 返回到数据定义的源代码，并为视图元素 CurrencyCode 添加元素注释 EndUSerText.label。将标签从**货币更改为货币代码**。

  1. 如下调整代码：

@Semantics.amount.currencyCode: 'CurrencyCode'
annual_salary         as AnnualSalary,
@EndUserText.label: 'Currency Key'
currency_code         as CurrencyCode,

  1. 激活数据定义。

  2. 按 Ctrl + F3 激活开发对象。

  3. 返回到 活动注释 视图，刷新显示并确认新标签现在已激活。

提示

要更轻松地查找特定注释，您可以首先折叠整个树，然后展开您感兴趣的元素和主要注释。

  1. 从活动注释视图的工具栏中，选择刷新 (F5)。或者，将光标置于视图上的任意位置，然后按 F5。

  2. 从活动注释视图的工具栏中，选择全部折叠。

  3. 展开 Z##_R_EMPLOYEE→CurrencyCode→@EndUserText。