Back to Details

sap-fiori-add-visual-filter

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SAP Fiori Visual Filter

SAP Fiori 可视化筛选器

Purpose

用途

Add chart-based filters (Bar/Line) to filter bar or value help dialog (OData V4).
为筛选栏或值帮助对话框（OData V4）添加基于图表的筛选器（柱状图/折线图）。

MANDATORY: Gather Required Inputs First

必填项：先收集所需输入

STOP and ASK the user for ALL of these inputs if ANY are missing from the prompt:
  1. Entity - Which entity to add the visual filter to
  2. Dimension field - The field to filter by (e.g., Category, Status, Destination)
  3. Measure field - The numeric field to aggregate (e.g., Amount, TotalPrice, ReservationPrice)
  4. Aggregation method - How to aggregate: sum, avg, min, or max
  5. Chart type - Bar or Line (recommend Bar as default)
DO NOT proceed with implementation until all inputs are confirmed.
如果提示中缺少以下任何一项，请停止操作并向用户询问所有这些输入：
  1. 实体 - 要添加可视化筛选器的实体
  2. 维度字段 - 用于筛选的字段（例如：Category、Status、Destination）
  3. 度量字段 - 要聚合的数值字段（例如：Amount、TotalPrice、ReservationPrice）
  4. 聚合方法 - 聚合方式：sum、avg、min或max
  5. 图表类型 - 柱状图或折线图（默认推荐柱状图）
在确认所有输入前，请勿继续实施。

CAP Implementation

CAP 实现

Enable Aggregation (MANDATORY)

启用聚合（必填）

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

Aggregated Property (Measure)

聚合属性（度量）

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

Chart Annotation

图表注解

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

PresentationVariant

展示变体

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

ValueList (on Dimension Field)

值列表（维度字段上）

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

SelectionFields

选择字段

cds
UI.SelectionFields: [Category]
cds
UI.SelectionFields: [Category]

Manifest configuration (MANDATORY)

清单配置（必填）

refer to the "Manifest Configuration" section below.
参考下方的“清单配置”部分。

ABAP RAP Implementation (4 Steps)

ABAP RAP 实现（4步）

CRITICAL: NEVER EDIT metadata.xml - IT IS READ-ONLY!

重要提示：请勿编辑metadata.xml - 它是只读的！

1. Backend CDS (MANDATORY) - Enable Aggregation Support

1. 后端CDS（必填）- 启用聚合支持

abap
@OData.applySupportedForAggregation: #FULL
define root view entity ZC_ENTITY
  provider contract TRANSACTIONAL_QUERY
  as projection on ZR_ENTITY
{
  @Aggregation.default: #SUM
  Amount;
  Category;
}
abap
@OData.applySupportedForAggregation: #FULL
define root view entity ZC_ENTITY
  provider contract TRANSACTIONAL_QUERY
  as projection on ZR_ENTITY
{
  @Aggregation.default: #SUM
  Amount;
  Category;
}

2. Backend Metadata Extension (MANDATORY) - Add Chart, PresentationVariant, SelectionField Annotations

2. 后端元数据扩展（必填）- 添加图表、展示变体、选择字段注解

abap
@UI.chart: [{
  qualifier: 'visualFilter',
  chartType: #BAR,
  dimensions: ['Category'],
  measures: ['Amount']
}]
@UI.presentationVariant: [{
  qualifier: 'visualFilter',
  visualizations: [{
    type: #AS_CHART,
    qualifier: 'visualFilter'
  }]
}]

annotate view ZC_ENTITY with
{
  @UI.selectionField: [{ position: 10 }]
  Category;

  @EndUserText.label: 'Amount'
  Amount;
}
abap
@UI.chart: [{
  qualifier: 'visualFilter',
  chartType: #BAR,
  dimensions: ['Category'],
  measures: ['Amount']
}]
@UI.presentationVariant: [{
  qualifier: 'visualFilter',
  visualizations: [{
    type: #AS_CHART,
    qualifier: 'visualFilter'
  }]
}]

annotate view ZC_ENTITY with
{
  @UI.selectionField: [{ position: 10 }]
  Category;

  @EndUserText.label: 'Amount'
  Amount;
}

3. Frontend (annotation.xml)

3. 前端（annotation.xml）

Chart Annotation:
xml
<Annotations Target="EntityType/Category">
<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>
</Annotations>
图表注解：
xml
<Annotations Target="EntityType/Category">
<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>
</Annotations>

4. Manifest configuration (MANDATORY)

4. 清单配置（必填）

refer to the "Manifest Configuration" section below.
参考下方的“清单配置”部分。

Manifest Configuration

清单配置

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

CRITICAL: Manifest Configuration Structure

重要提示：清单配置结构

NEVER nest visualFilter inside a 
settings
property!
请勿将visualFilter嵌套在
settings
属性内！

Testing

测试

CAP Projects

CAP 项目

bash
npm run watch-<app-name>  # e.g., npm run watch-manage-travel
bash
npm run watch-<app-name>  # 例如：npm run watch-manage-travel

or use generic watch script if available

或使用通用watch脚本（如果可用）

cds watch
undefined
cds watch
undefined

RAP Projects

RAP 项目

bash
npm run start-mock # Needs metadata refresh

npm start          # No refresh needed - fetches metadata from live backend at runtime
  • Consult fiori mcp server if available on how to refresh metadata for sap/cloud systems in case of RAP
bash
npm run start-mock # 需要刷新元数据

npm start          # 无需刷新 - 运行时从实时后端获取元数据
  • 若使用SAP云系统的RAP，请参考fiori mcp服务器了解如何刷新元数据

Key Differences

主要差异

CAP:
  • Aggregation + measures defined in CDS
  • Uses DynamicMeasures
  • Aggregation and chart defined in same place
RAP:
  • Aggregation defined in backend CDS only
  • Uses Measures (not DynamicMeasures)
  • Metadata is read-only
CAP：
  • 聚合和度量在CDS中定义
  • 使用DynamicMeasures
  • 聚合和图表在同一位置定义
RAP：
  • 仅在后端CDS中定义聚合
  • 使用Measures（而非DynamicMeasures）
  • 元数据为只读

Common Mistakes

常见错误

  • Backend Changes are not activated.
  • Qualifier mismatch between Chart, ValueList, PresentationVariant, and manifest
  • Wrong path in manifest (use full vocabulary path)
  • Missing SelectionField annotation
  • Non-numeric measure field
  • Missing compact visual layout configuration in manifest
RAP:
  • Missing backend aggregation support
  • Using DynamicMeasures instead of Measures
  • Adding Common.ValueList in backend instead of frontend (ValueList MUST be in frontend annotation.xml)
  • Adding UI annotations directly in CDS projection view instead of metadata extension
  • Trying to use @Consumption.valueHelpDefinition for visual filters (that's for value help dialogs, not visual filters)
  • 后端更改未激活
  • 图表、值列表、展示变体和清单之间的限定符不匹配
  • 清单中的路径错误（使用完整词汇路径）
  • 缺少SelectionField注解
  • 度量字段非数值类型
  • 清单中缺少紧凑可视化布局配置
RAP：
  • 缺少后端聚合支持
  • 使用DynamicMeasures而非Measures
  • 在后端添加Common.ValueList而非前端（ValueList必须在前端annotation.xml中）
  • 在CDS投影视图中直接添加UI注解而非元数据扩展
  • 尝试使用@Consumption.valueHelpDefinition实现可视化筛选器（该注解用于值帮助对话框，而非可视化筛选器）

Best Practices

最佳实践

  • Always activate backend changes in ADT MCP before testing
  • Use 1 dimension + 1 measure per visual filter
  • Prefer Bar charts for better readability
  • Keep qualifier names consistent across all annotations
  • Test with different data volumes
  • Always include layout: "CompactVisual" and initialLayout: "Visual" in manifest
RAP Specific:
  • ALWAYS use ADT MCP to modify backend files when available
  • Chart + PresentationVariant → Backend metadata extension (.ddlx.acds)
  • Common.ValueList → Frontend annotation.xml (CANNOT be in backend)
  • 测试前始终在ADT MCP中激活后端更改
  • 每个可视化筛选器使用1个维度+1个度量
  • 优先选择柱状图以提高可读性
  • 所有注解中的限定符名称保持一致
  • 使用不同数据量进行测试
  • 清单中始终包含layout: "CompactVisual"和initialLayout: "Visual"
RAP 特定：
  • 若可用，始终使用ADT MCP修改后端文件
  • 图表+展示变体 → 后端元数据扩展（.ddlx.acds）
  • Common.ValueList → 前端annotation.xml（不能在后端）

References

参考资料