SAP CAP篇十：理解Fiori UI的Annoation定义

本系列此前的文章

SAP CAP篇一: 快速创建一个Service，基于Java的实现
SAP CAP篇二：为Service加上数据库支持
SAP CAP篇三：定义Model
SAP CAP篇四：为CAP添加Fiori Elements程序(1)
SAP CAP篇五：为CAP添加Fiori Elements程序(2)
SAP CAP篇六：为CAP添加Fiori Elements程序(3)
SAP CAP篇七：为CAP添加Fiori Launchpad入口 (Sandbox环境)
SAP CAP篇八：为CAP添加App Router并支持Fiori Launchpad (Sandbox环境)
SAP CAP篇九：升级为SAP CDS 7.0, CAP Java 2以及Spring Boot 3

官方文档和基础概念

官方文档中当然包含了Fiori UI的部分，不过要弄懂整个概念，也得先从OData的部分开始看起。

一切从根源说起：

• 不论是SAP CAP还是SAP RAP，其实都拓展了OData的定义。
• OData的设计初衷是格式化REST风格的API，通过$metadata, $count, $filter, $select等定义规范了POST/GET等一系列操作；
• SAP CDS Annotation其实是在OData的metadata中添加了额外的为了UI（其实这里特指Fiori UI）定义的内容，用来规范Fiori UI程序的组成。
• SAP CDS Annotation的设计理念应该是，最大简化界面层面的开发，甚至可以不写一行界面代码的方式生成标准、统一的前台程序。

SAP CAP对Fiori UI的支持

理解了上述的基础概念，下面就基于前面几篇的项目，研究下SAP CAP对Fiori UI是如何通过Annotation实现的。

package.json的新增内容

在SAP CAP篇四：为CAP添加Fiori Elements程序(1) 为项目添加Fiori Elements程序时，其实Application Generator自动在项目的package.json文件中添加了如下依赖：

  "devDependencies": {
    "@sap/ux-specification": "^1.102.23"
  }

除了添加的依赖之外，还有如下额外的部分：

  "sapux": [
    "app/manage-books",
    "app/browse-books"
  ],

这里每条新增的项目就对应每个新添加的Fiori Elements。

Annotation定义

上述package.json只是让编译器知道在编译时查找Annotation定义，以输出Annotation相关的定义为Metadata。

Annotation定义则是保存在对应的Annotation CDS文件中。具体来说，在本例中，对应的Annotation定义存放在fiori-service.cds中。

本篇没法具体介绍所有的Annotation，仅使用最常用的List Page来进行说明。

List Page

List Page由上面的Filter Bar加Table构成。

• 前者由UI.SelectionFields定义。
• 后者由UI.LineItem来定义。这里定义的LineItem其实是定义Table中的Column。

annotate service.Books with @(
    UI.SelectionFields: [ ID, title, descr ],
    UI.LineItem : [
        {
            $Type : 'UI.DataField',
            Value : title,
        },
        {
            $Type : 'UI.DataField',
            Value : descr,
        },
        {
            $Type : 'UI.DataField',
            Value : stock,
        },
        {
            $Type : 'UI.DataField',
            Value : price,
        },
        {
            $Type : 'UI.DataField',
            Value : currency_code,
        },
        {
            $Type: 'UI.DataField',
            Value: category_ID
        }
    ]
);

生成的Edmx文件

与SAP CAP Node.js版本不同，SAP CAP Java项目只能通过生成的edmx文件来查看上述Annotation。

参见项目 srv\src\main\resources\edmx文件夹，通常其中有很多xml文件，文件命名中指定了相关的语言版本。

      <Annotations Target="AdminService.Books">
        <Annotation Term="UI.SelectionFields">
          <Collection>
            <PropertyPath>IDPropertyPath>
            <PropertyPath>titlePropertyPath>
            <PropertyPath>descrPropertyPath>
          Collection>
        Annotation>
        <Annotation Term="UI.LineItem">
          <Collection>
            <Record Type="UI.DataField">
              <PropertyValue Property="Value" Path="title"/>
            Record>
            <Record Type="UI.DataField">
              <PropertyValue Property="Value" Path="descr"/>
            Record>
            <Record Type="UI.DataField">
              <PropertyValue Property="Value" Path="stock"/>
            Record>
            <Record Type="UI.DataField">
              <PropertyValue Property="Value" Path="price"/>
            Record>
            <Record Type="UI.DataField">
              <PropertyValue Property="Value" Path="currency_code"/>
            Record>
            <Record Type="UI.DataField">
              <PropertyValue Property="Value" Path="category_ID"/>
            Record>
          Collection>
        Annotation>

对应代码及branch

与本文配套的代码参见这里。

本篇对应的branch是6_cds7。