Fiori RAP开发必备：5个实用CDS注解详解与场景应用

在进行SAP Fiori RAP（RESTful Application Programming）开发时，CDS注解是塑造UI页面显示逻辑的强大工具。面对字段隐藏、格式调整、图标显示等常见需求，掌握几个关键的注解往往能事半功倍。本文将分享几个在 RAP开发 实践中高频出现且非常实用的CDS注解，并附上代码示例和场景说明，希望对你的企业级应用开发有所帮助。

1. 确保关键字段在列表行中始终可见 (@UI.lineItem.importance)

当实体（Entity）中定义的字段较多时，在前台列表页面中，排在后面的字段可能会因为屏幕空间不足而被隐藏或收纳起来。如果你希望某个重要字段（如金额、状态）始终显示在行项目（lineItem）中，可以使用 importance 属性。

通过设置 importance: #HIGH，可以提升字段的显示优先级。

@EndUserText.label: ‘超概金额'
@Semantics.amount.currencyCode : ‘twaer'
@UI.identification: [ { position: 50 },
                      { qualifier: ‘basic'} ]
@UI.lineItem: [ { position: 50 , importance: #HIGH } ]
      gapamt   : bp_wjt;

2. 启用长文本/多行文本显示 (@UI.multiLineText)

当某个字段需要支持输入或展示较长内容时（例如备注、描述），我们希望它在UI上能以多行文本域的形式呈现，而不是单行输入框。这时，@UI.multiLineText 注解就派上用场了。

@UI.multiLineText: true  // 启用长文本多行显示
      longtext_field : abap.string;

3. 控制金额字段的货币单位显示 (@Metadata.ignorePropagatedAnnotations)

金额字段在默认情况下通常会与关联的货币代码字段绑定，在页面上同时显示金额和货币单位（如“1,000.00 USD”）。但有时业务场景只需要展示纯数字金额。

一种实现方式是：在创建投影视图或消费视图时，去掉从底层数据源自动传播过来的 @Metadata.ignorePropagatedAnnotations: true 注解。这个注解的作用是指示编译器忽略从底层实体传播上来的注解。将其移除（或设为false）后，视图层可以重新定义该字段的语义，使其不绑定货币单位。

以下是实体定义中常出现的元数据块，其中的 @Metadata.ignorePropagatedAnnotations: true 在特定场景下可能需要被移除：

@AbapCatalog.viewEnhancementCategory: [#NONE]
@AccessControl.authorizationCheck: #NOT_REQUIRED
@EndUserText.label: ‘ZI_TESTEKPOINFO'
@Metadata.ignorePropagatedAnnotations: true // 关注此注解
@ObjectModel.usageType:{
    serviceQuality: #X,
    sizeCategory: #S,
    dataClass: #MIXED
}

4. 为对象页面添加标题图标 (@UI.headerInfo.typeImageUrl)

为了让UI界面更加直观和友好，我们经常需要在对象页面的标题区域添加一个图标。这可以通过在 @UI.headerInfo 中设置 typeImageUrl 属性来实现。

SAP Fiori 提供了丰富的图标库，你可以通过官方图标浏览器查询所有可用图标的名称：

https://sapui5.hana.ondemand.com/test-resources/sap/m/demokit/iconExplorer/webapp/index.html#/overview

在CDS视图的注解中，可以这样引用图标：

@Metadata.layer: #CORE
@UI: {
  headerInfo: {
    typeName: ‘固定资产盘点’,
    typeNamePlural: ‘固定资产盘点’,
    typeImageUrl: ‘sap-icon://inventory’,  // 添加图标
    title: {
      type: #STANDARD,
      label: ‘盘点编号’,
      value: ‘Zzcpdbh’
    },
    description: {
      type: #STANDARD,
      label: ‘公司代码’,
      value: ‘Bukrs’
    }
  }
}

5. 调整带描述字段的文本显示顺序 (@UI.textArrangement)

当一个字段绑定了文本描述（例如物料编号Matnr绑定物料描述Maktx）时，默认显示格式通常是“描述（编号）”。如果想调整这个顺序，变成“编号 - 描述”或者自定义顺序，可以使用 @UI.textArrangement 注解。

它支持两个主要的枚举值：

• #TEXT_FIRST: 文本描述在前。
• #TEXT_LAST: 文本描述在后。

@ObjectModel.text.element: [‘Maktx’] // 绑定文本字段
@UI.textArrangement: #TEXT_FIRST // 设置文本显示在前
      Matnr,

以上就是在 Fiori RAP 项目开发中经常用到的几个CDS注解技巧。它们虽然看起来是细节，但却能切实解决UI展示上的痛点，提升应用的用户体验。如果你在SAP开发中还有其他实用的注解技巧，欢迎在云栈社区与我们交流分享。