sap-fiori-analytical-chart

SAP Fiori 分析图表

用途

添加分析图表 + 表格（混合视图），用于可视化汇总数据。

---

先决条件

CAP 项目：

• ✅ VS Code 或 SAP Business Application Studio (BAS) - 两种环境均受支持
• ✅ Fiori MCP Server - 修改 Fiori 应用时必需（仅限 VS Code）

ABAP RAP 项目：

• ✅ 仅限 VS Code - ABAP Development Tools 扩展仅适用于 VS Code
• ✅ Fiori MCP Server - 修改 Fiori 应用时必需
• ✅ ABAP Development Tools for VS Code extension - 后端开发时必需（包含用于 RAP 操作的 ADT MCP server）

---

必须：先收集所需输入

如果提示中缺少以下任何输入，请停止并向用户询问所有这些输入：

1. 实体 - 要添加分析图表的实体
2. 维度字段 - 用于分组的字段（例如 Category、Status、Destination）
3. 度量字段 - 要汇总的数值字段（例如 Amount、TotalPrice、ReservationPrice）
4. 聚合方法 - 聚合方式（请参见下方有效值）
5. 图表类型 - Bar、Column、Line、Pie、HeatMap、Waterfall、HorizontalWaterfall
6. 显示模式 - 图表的显示方式：
   • 单独的选项卡（方案 2）
   • 混合视图（方案 1）

在确认所有输入之前，请勿继续实施。

---

CAP 实现

启用聚合

@Aggregation.ApplySupported: {
  Transformations: ['aggregate','groupby'],
  AggregatableProperties: [{Property: Amount}],
  GroupableProperties: [Category]
}

聚合属性

Analytics.AggregatedProperty #Amount_avg: {
  Name: 'Amount_avg',
  AggregatableProperty: Amount,
  AggregationMethod: 'average',
  ![@Common.Label]: 'Average Amount'
}

有效的 AggregationMethod 值（小写字符串）：

• sum - 非空值的总和
• min - 非空值中的最小值
• max - 非空值中的最大值
• average - 非空值总和除以非空值数量
• countdistinct - 不计空值的不同值数量

⚠️ 重要：必须是小写字符串（例如 'sum'），不能是枚举（例如 #SUM）。使用枚举会导致 SQL 生成错误。

图表

UI.Chart #AnalyticalChart: {
  $Type: 'UI.ChartDefinitionType',
  Title: 'Chart Title',
  ChartType: #Column,
  Dimensions: [Category],
  DynamicMeasures: ['@Analytics.AggregatedProperty#Amount_avg'],
  MeasureAttributes: [{
    $Type: 'UI.ChartMeasureAttributeType',
    DynamicMeasure: '@Analytics.AggregatedProperty#Amount_avg',
    Role: #Axis1
  }],
  DimensionAttributes: [{
    $Type: 'UI.ChartDimensionAttributeType',
    Dimension: Category,
    Role: #Category
  }]
},
UI.PresentationVariant #ChartView: {
  $Type: 'UI.PresentationVariantType',
  Text: 'Chart View',
  Visualizations: ['@UI.Chart#AnalyticalChart']
},
UI.PresentationVariant #TableView: {
  $Type: 'UI.PresentationVariantType',
  Text: 'Table View',
  Visualizations: ['@UI.LineItem']
}

✅ 使用 DynamicMeasures

---

ABAP RAP 实现（3 个步骤 + Manifest 配置）

重要：切勿编辑 metadata.xml - 它是只读文件！

⚠️ 实施前检查清单 - 请先验证

缺少以下任何一项都会导致应用失败或无法加载：

• 在投影视图（ZC_*）上添加 @OData.applySupportedForAggregation: #FULL
• 在度量字段上添加 @Aggregation.default: #AVG（或 #SUM、#MIN、#MAX）
• 在元数据扩展中添加带正确 qualifier 的 @UI.chart 注解
• 配置 Manifest targets.<ListReport>.options.settings.views.paths
• 激活所有 CDS 对象

---

1. 后端投影视图（必需）- 启用聚合支持

⚠️ 重要：@OData.applySupportedForAggregation 注解是必需的

缺少此注解时：

• OData 服务将不支持聚合
• 应用将无法加载（空白屏幕/错误）
• 图表注解将被忽略

放置位置：

• ✅ 必须位于带有 TRANSACTIONAL_QUERY 合约的投影视图（ZC_* 或 ZZZC_*）上
• ❌ 不能位于接口视图（ZR_* 或 ZZZR_*）上

正确示例：

// MANDATORY! Must be present!
@OData.applySupportedForAggregation: #FULL
define root view entity ZC_ENTITY
  provider contract TRANSACTIONAL_QUERY
  as projection on ZR_ENTITY
{
  @Aggregation.default: #AVG  // Specify aggregation method for measure
  Amount;
  Category;  // Dimension field (no aggregation annotation needed)
}

错误示例：

// ❌ WRONG - Don't put on interface view
// WRONG PLACE!
@OData.applySupportedForAggregation: #FULL
define root view entity ZR_ENTITY
  as select from TABLE

2. 后端元数据扩展（必需）- 添加 Chart、PresentationVariant 注解

⚠️ 重要：@UI.chart 和 @UI.presentationVariant 是实体级（头部）注解。 请将它们放在头部区域 — 位于 annotate view ZC_ENTITY with 之前（与 @UI.headerInfo.* 并列），不要放在 { ... } 字段区域内，也不要放在字段上（例如维度字段）。 将 @UI.chart 附加到字段会导致激活失败，并显示：Annotation 'UI.chart.qualifier' used at wrong position (wrong scope)。

// ↓↓↓ HEADER SCOPE: these go BEFORE `annotate view`, never on a field ↓↓↓
@UI.chart: [{
  qualifier: 'AnalyticalChart',
  title: 'Chart Title',
  description: 'Chart description',
  chartType: #COLUMN,
  dimensions: ['Category'],
  measures: ['Amount'],
  dimensionAttributes: [{
    dimension: 'Category',
    role: #CATEGORY
  }],
  measureAttributes: [{
    measure: 'Amount',
    role: #AXIS_1
  }]
}]
@UI.presentationVariant: [{
  qualifier: 'ChartView',
  text: 'Chart View',
  visualizations: [{
    type: #AS_CHART,
    qualifier: 'AnalyticalChart'
  }]
},
{
  qualifier: 'TableView',
  text: 'Table View',
  visualizations: [{
    type: #AS_LINEITEM
  }]
}]
annotate view ZC_ENTITY with
{
  // Other field annotations...
  @EndUserText.label: 'Amount'
  Amount;
  
  @EndUserText.label: 'Category'
  Category;
}

3. 验证注解是否生效（必需）

激活 DDLS 和 DDLX 后，验证更改已生效：

⚠️ 重要：DDLS 和 DDLX 是两个独立对象

投影视图（DDLS 文件）和元数据扩展（DDLX 文件）是两个独立的 ABAP 开发对象，只是实体名称相同。

要点：

• DDLS = 数据定义（投影视图）——包含实体定义、关联、字段和数据注解
• DDLX = 元数据扩展——包含 UI 注解（@UI.chart、@UI.presentationVariant、字段标签等）
• 两者必须分别激活——激活其中一个不会激活另一个
• 分析图表正常工作需要两者都存在

激活：

• 使用 ABAP ADT MCP 激活 ABAP 对象
• 分别激活 DDLS 文件和 DDLX 文件

验证步骤：

1. 验证激活状态：

   • 检查激活工具的输出，确认显示成功消息
   • 确认激活过程中没有报告错误
   • DDLS 和 DDLX 都必须显示激活成功

2. 检查 OData $metadata：

   • 在浏览器中打开服务 URL：<service-url>/$metadata
   • 搜索：<Annotation Term="UI.Chart" Qualifier="AnalyticalChart">
   • 同时验证：<Annotation Term="UI.PresentationVariant" Qualifier="ChartView">
   • 如果 $metadata 中缺少这些注解，则说明 DDLX 未激活，或者需要重新发布服务绑定

---

清单配置（CAP 和 RAP 通用）

方法 1：混合视图（图表和表格同时显示）

清单：

"targets": {
  "<ListReport>": {  // Replace with your actual List Report target name
    "type": "Component",
    "name": "sap.fe.templates.ListReport",
    "options": {
      "settings": {
        "contextPath": "/<YourEntity>",  // Replace with your entity set path
        "views": {
          "paths": [
            {
              "primary": [
                { "annotationPath": "com.sap.vocabularies.UI.v1.Chart#AnalyticalChart" }
              ],
              "secondary": [
                { "annotationPath": "com.sap.vocabularies.UI.v1.LineItem" }
              ],
              "defaultPath": "both"
            }
          ]
        }
      }
    }
  }
}

方法 2：使用 PresentationVariant 的多个视图标签页

清单：

"targets": {
  "<ListReport>": {  // Replace with your actual List Report target name
    "type": "Component",
    "name": "sap.fe.templates.ListReport",
    "options": {
      "settings": {
        "contextPath": "/<YourEntity>",  // Replace with your entity set path
        "views": {
          "paths": [
            {
              "key": "ChartView",
              "annotationPath": "com.sap.vocabularies.UI.v1.PresentationVariant#ChartView"
            },
            {
              "key": "TableView",
              "annotationPath": "com.sap.vocabularies.UI.v1.PresentationVariant#TableView"
            }
          ]
        }
      }
    }
  }
}

---

测试

有关详细测试说明，请参阅 sap-fiori-app-development 技能中的应用预览指南部分，其中包括：

• 使用监视脚本测试 CAP 项目
• 使用实时后端与模拟模式测试独立 Fiori 项目
• 后端更改后的元数据刷新流程

---

实施顺序（RAP）

按以下顺序操作，避免出现错误：

1. 修改投影视图（ZC_ENTITY）——DDLS 文件

   • 在顶部添加 @OData.applySupportedForAggregation: #FULL
   • 为度量字段添加 @Aggregation.default: #AVG
   • 使用 ABAP ADT MCP 激活
   • 验证激活成功

2. 修改元数据扩展（ZC_ENTITY）——DDLX 文件

   • 添加带限定符的 @UI.chart 注解
   • 添加 @UI.presentationVariant 注解
   • 使用 ABAP ADT MCP 激活
   • 验证激活成功

3. 验证注解是否生效（请参阅上文 ABAP RAP 实施部分中的步骤 3）

4. 更新 Fiori 应用清单

   • 在 targets.<ListReport>.options.settings 下添加 views.paths（不要放在 controlConfiguration 内）
   • 保存 manifest.json

5. 测试

   • 运行 npm start（获取实时元数据——无需重新发布）
   • 无需重新发布服务绑定
   • 如果图表未显示，请检查浏览器控制台是否出现 "Annotation Path ... not found" 错误

---

故障排除

症状：控制台错误 "Annotation Path for the primary visualization ... not found"

完整错误消息：

Annotation Path for the primary visualization com.sap.vocabularies.UI.v1.Chart#AnalyticalChart not found

**原因：**元数据扩展（DDLX）未激活，因此 OData $metadata 中没有公开 @UI.chart 注解。

解决方案：

1. 使用 ABAP ADT MCP 激活 DDLX 文件
2. 验证激活成功（检查工具输出中是否有错误）
3. 验证注解是否出现在 $metadata 中：<service-url>/$metadata（搜索 Chart#AnalyticalChart）
4. 重启 Fiori 应用：npm start

**注意：**即使编辑了 DDLX，也必须明确激活后才会生效。DDLS 和 DDLX 是两个独立对象。

---

症状：应用无法加载／显示空白屏幕／图表不可见

原因 1： 缺少 @OData.applySupportedForAggregation: #FULL

• 解决方案： 添加到投影视图（ZC_*），激活后重启应用

原因 2： 注解位于错误的视图上

• 解决方案： 从接口视图（ZR_）移至投影视图（ZC_）

原因 3： 度量字段不是数值型

• 解决方案： 确认字段为数值类型（金额、数量、小数、整数）

原因 4： 清单中的限定符错误

• 解决方案： 确认清单中的限定符与 @UI.chart: [{ qualifier: 'AnalyticalChart' }] 匹配

原因 5： 度量缺少 @Aggregation.default

• 解决方案： 为度量字段添加 @Aggregation.default: #AVG（或 #SUM、#MIN、#MAX）

原因 6： DDLX 未激活（请参见上方的控制台错误）

• 解决方案： 使用 ABAP ADT MCP 激活元数据扩展（DDLX）文件

症状：图表显示，但数据不正确

原因： 聚合方法错误

• 解决方案： 更改 @Aggregation.default 的值（#AVG、#SUM、#MIN、#MAX）

---

主要区别

CAP：

• 在 CDS 中定义聚合和度量
• 使用 DynamicMeasures

RAP：

• 仅在后端 CDS 中定义聚合
• 使用 Measures

---

常见错误

常见问题：

• 清单配置错误
• 混用方法 1 和方法 2 的配置
• 度量字段不是数值型
• 限定符错误（清单与注解不匹配）

RAP 特有问题：

• ❌ 最常见： 缺少 @OData.applySupportedForAggregation: #FULL → 应用无法加载
• ❌ 将聚合注解放在接口视图上，而不是投影视图上
• ❌ 度量字段缺少 @Aggregation.default
• ❌ 更改后忘记激活 CDS 对象
• ❌ 使用了错误的视图契约（必须为 TRANSACTIONAL_QUERY）

---

最佳实践

• 使用 1 个维度和 1–2 个度量
• 优先选择柱形图／条形图
• 方法 1：使用 "defaultPath": "both"，在同一视图中并排显示图表和表格
• 方法 2：使用 PresentationVariant，在不同视图页签中分别显示图表或表格

参考资料

• SAP Fiori Elements 分析列表报表：https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/topic/floorplanListReport/analyticalListReport
• ABAP RAP 聚合支持：https://help.sap.com/docs/abap-cloud/abap-rap/projection-view