sap-fiori-add-visual-filter

SAP Fiori 可视化筛选器

用途

向筛选栏或值帮助对话框（OData V4）添加基于图表的筛选器（柱形图／折线图）。

---

必须：先收集所需输入

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

1. 实体 - 要添加可视化筛选器的实体
2. 维度字段 - 用于筛选的字段（例如 Category、Status、Destination）
3. 度量字段 - 要聚合的数值字段（例如 Amount、TotalPrice、ReservationPrice）
4. 聚合方法 - 聚合方式：sum、avg、min 或 max
5. 图表类型 - Bar 或 Line（默认推荐 Bar）

在所有输入都确认之前，不要继续实施。

---

CAP 实现

启用聚合（必须）

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

聚合属性（度量）

Analytics.AggregatedProperty #Amount_sum : {
  $Type: 'Analytics.AggregatedPropertyType',
  Name: 'Amount_sum',
  AggregatableProperty: Amount,
  AggregationMethod: 'sum'
}

图表注解

UI.Chart #visualFilter : {
  ChartType: #Bar,
  Dimensions: [Category],
  DynamicMeasures: ['@Analytics.AggregatedProperty#Amount_sum']
}

✅ 使用 DynamicMeasures

PresentationVariant

UI.PresentationVariant #visualFilter: {
  Visualizations: ['@UI.Chart#visualFilter']
}

ValueList（在维度字段上）

Category @Common.ValueList #visualFilter: {
  $Type: 'Common.ValueListType',
  CollectionPath: 'EntityName',
  Parameters: [
    { $Type: 'Common.ValueListParameterInOut', LocalDataProperty: Category, ValueListProperty: 'Category' }
  ],
  PresentationVariantQualifier: 'visualFilter'
}

SelectionFields

UI.SelectionFields: [Category]

---

ABAP RAP 实现

• 元数据中的 metadata.xml（RAP）必须提供 Aggregation.ApplySupported 和 Aggregation.CustomAggregate 注解。否则，需要进行以下后端配置。

后端 CDS（必须）

@OData.applySupportedForAggregation: #FULL
define root view entity ZC_ENTITY
  provider contract analytical_query
  as projection on ZI_ENTITY
{
  key EntityID,

  @Aggregation.default: #SUM
  Amount,

  Category
}

图表注解

<Annotation Term="UI.Chart" Qualifier="visualFilter">
  <Record Type="UI.ChartDefinitionType">
    <PropertyValue Property="ChartType" EnumMember="UI.ChartType/Bar"/>
    <PropertyValue Property="Dimensions">
      <Collection>
        <PropertyPath>Category</PropertyPath>
      </Collection>
    </PropertyValue>
    <PropertyValue Property="Measures">
      <Collection>
        <PropertyPath>Amount</PropertyPath>
      </Collection>
    </PropertyValue>
  </Record>
</Annotation>

✅ 使用 Measures（而不是 DynamicMeasures）
❌ 元数据为只读

PresentationVariant 注解

<Annotation Term="UI.PresentationVariant" Qualifier="visualFilter">
  <Record Type="UI.PresentationVariantType">
    <PropertyValue Property="Visualizations">
      <Collection>
        <AnnotationPath>@UI.Chart#visualFilter</AnnotationPath>
      </Collection>
    </PropertyValue>
  </Record>
</Annotation>

ValueList 注解

<Annotation Term="Common.ValueList" Qualifier="visualFilter">
  <Record Type="Common.ValueListType">
    <PropertyValue Property="CollectionPath" String="EntityName"/>
    <PropertyValue Property="PresentationVariantQualifier" String="visualFilter"/>
    <PropertyValue Property="Parameters">
      <Collection>
        <Record Type="Common.ValueListParameterInOut">
          <PropertyValue Property="LocalDataProperty" PropertyPath="Category"/>
          <PropertyValue Property="ValueListProperty" String="Category"/>
        </Record>
      </Collection>
    </PropertyValue>
  </Record>
</Annotation>

SelectionFields 注解

<Annotation Term="UI.SelectionFields">
  <Collection>
    <PropertyPath>Category</PropertyPath>
  </Collection>
</Annotation>

---

Manifest 配置（必需）

"@com.sap.vocabularies.UI.v1.SelectionFields": {
  "layout": "CompactVisual",
  "initialLayout": "Visual",
  "filterFields": {
    "Category": {
      "visualFilter": {
        "valueList": "com.sap.vocabularies.Common.v1.ValueList#visualFilter"
      }
    }
  }
}

✅ 将筛选字段关联到可视化筛选器图表
✅ 将初始布局设为可视化模式

---

测试

CAP 项目

npm run watch-<app-name>  # e.g., npm run watch-manage-travel
# or use generic watch script if available
cds watch

RAP 项目

npm run start-mock # Needs metadata refresh

npm start          # No refresh needed - fetches metadata from live backend at runtime

• 如果有可用的 fiori mcp server，请咨询其如何为 sap/cloud 系统刷新元数据，尤其是在 RAP 场景下

---

主要区别

• CAP：在 CDS 中定义 DynamicMeasures 和 AggregatedProperty
• RAP：仅在后端 CDS 中使用 Measures 和 @Aggregation.default
• CAP：在同一位置定义聚合和图表
• RAP：元数据为只读，必须在后端 CDS 中配置。
• 限定符：Chart、ValueList 和 manifest 必须使用相同的限定符（#visualFilter）

---

常见错误

• 缺少后端聚合配置
• Chart、ValueList、PresentationVariant 和 manifest 之间的限定符不匹配
• manifest 中的路径错误（使用完整的词汇路径）
• RAP 项目使用 DynamicMeasures 而不是 Measures
• 在 ValueList 中忘记设置 PresentationVariantQualifier
• 缺少 SelectionFields 注解

---

最佳实践

• 使用柱形图（最常见且推荐）
• 每个筛选栏最多设置 3–5 个可视化筛选器
• 始终先配置后端聚合
• 始终使用一致的限定符
• 使用真实数据进行测试，以验证聚合是否正常工作