05 · Fiori elements 特性全集:完整教程

目标:把官方 Feature Showcase(特性演示应用)在本地跑起来,用「改一个注解(annotation)→ 刷新 → 观察界面」的循环,把 SAP Fiori elements for OData V4 的表格、表单、页面、操作、图表等特性一次性建立直觉——看到需求时能说出「用哪个注解、写在哪个文件、界面会变成什么样」。 预计:3–4 小时(只求跑通约 1 小时;逐个特性走查 3–4 小时)| 难度:中 | 前置课程:UX405 / UX406 / UX410

阅读方式:本教程以本地 CAP(SAP Cloud Application Programming Model)运行为主线,命令可以直接复制。部署到 SAP BTP 放在步骤 11(可选)。官方原文以文字和注解片段为主、几乎没有操作截图,所以正文用「注解代码 + 特性对照表 + 预期效果」讲透每一个特性。全文只含 1 张本案例真实成品截图(用在「你会做出什么」一节,并在步骤 3 里逐区拆解);另外配了 10 张 SAP 官方课程 UX405 的同类界面示意图/楼层图——它们不是本案例截图,只用于帮助理解 Fiori elements 的页面结构与特性,每张图注都标了来源,界面细节请以你自己运行出来的结果为准。本教程不伪造本案例的运行截图。

你会做出什么

你会得到一个跑在本机、可以随便改的 FE feature showcase:它是一个 CAP 后端 + SAP Fiori elements for OData V4 前端的完整应用,把所有「注解驱动」的 UI 特性做成了真实可点的页面。跑通后你能在浏览器里看到:

  • 四种页面形态:List Report(列表报表)、Object Page(对象页)、Custom Object Page(用 Flexible Programming Model 自定义的对象页)、Worklist(工作清单,即去掉筛选栏的列表报表);

  • 一个 OData V4 服务:服务名 LROPODataService(路径 /srv1),实体包括根实体 RootEntities、子实体 ChildEntities1/2/3、联系人 Contacts、地区 Regions、订单 Orders、组织单元 OrganizationalUnits、图表数据 ChartDataEntities 等;

  • 几十种可点开的特性:变式管理、多视图切换、值帮助、依赖筛选、表格操作与菜单按钮、树表格、评分/进度/微图列、联系人快速查看、字段组多列、图片列、单位货币列、对象页标题区分面、表单、侧边内容、图表分节、底部工具栏、自定义操作等——每一项都对应仓库里一段 CDS 注解或 manifest.json 配置;

  • 一个可反复做的实验回路:改一行注解 → 保存 → 服务自动重编译 → 浏览器刷新 → 界面对应变化。这个回路才是本案例真正的产出。

跑通后的 List Report 长这样(这是本案例唯一一张真实截图,界面上的每个区域在步骤 3 都会对上代码):

跑通后的 FE feature showcase 列表报表界面:变式管理、筛选栏、多视图标签、操作工具栏、图片列、语义键列、货币列、工具提示列、子弹微图、快速查看列、字段组列、径向微图和行内导航都出现在同一个表格里

从上到下你能认出这些区域:SAP 启动栏里的 FE feature showcase 应用标题;标题行的 Standard 变式下拉;筛选栏的搜索框、Editing Status: All(草稿编辑状态筛选)、Field with semantic key、Property with currency、Rating filter 星级筛选、Go 按钮和 Adapt Filters (1);第一行 4 个视图标签(SelectionVariant / SelectionPresentationVariant / 另一个实体集);第二行表格标题 Root entities 与两个分段按钮(单表格多视图);操作工具栏的 Show Details、criticalAction、Custom action、Menu Button、Create、Delete;表格列里的 Image、加粗的语义键、300 JPY / 400.00 EUR、工具提示数字、红色与灰色子弹微图、fieldValue 快速查看链接、Admin data (field group) 多字段列、Radial chart 100% / 66.7% 的环形微图,最右侧的购物车图标(行内导航)与 > 箭头(进对象页)。行首的红色竖条是 criticality(关键度)高亮,勾选框说明表格开了多选。

学完这一篇,你应该能做到:拿到一个新的 Fiori elements 需求,先判断它属于「页面结构」「表格列」「表单」「操作」「图表」「扩展点」中的哪一类,再去改对应的注解或 manifest.json,而不是凭感觉改 XML 视图。

架构与原理

业务场景:数据只是载体,特性才是主角

这个仓库的业务模型是刻意「造」出来的:根实体 RootEntities 带一批类型各异的字段(字符串、整数、金额、单位、日期、图片 URL、联系人关联等),再挂上子实体、联系人、地区、订单、组织单元和图表数据。它不模拟某个真实行业流程,而是保证每一种 Fiori elements 特性都能找到合适的字段和关联去演示。所以你在界面上看到的「Root entity 1 with delete not possible」「Root entity 2 with update not possible」这类别扭的语义键文本,是故意写进示例数据的——用来观察「删除/更新按钮随选中行动态启用禁用」这类特性。

读这个案例时不要纠结业务合理性,要盯着三件事:这个界面元素由哪条注解产生?这条注解写在哪个 target 上?改哪里能让它变样?

分层架构:注解在中间,前端几乎不写代码

层

作用

在本案例中的位置

你改它的频率

数据模型层

CAP 实体、关联、类型定义

仓库的 db/、srv/ 下的 CDS 模型(persistence.* 实体)

低

服务层

把模型投影成 OData V4 服务,定义操作(action)、函数、服务路径

srv/ 下的服务 CDS 与 srv/list-report-srv.js(CAP 事件处理)

中

注解层

用 UI.*/Common.*/Capabilities.* 等词汇表描述「业务语义如何变成界面」

app/listreport-objectpage/ 下的 layout.cds、layouts_RootEntities.cds、labels.cds、value-helps.cds、capabilities.cds、field-control.cds 等;Worklist 应用另有 app/worklist/annotations.cds

高(本教程主战场)

页面配置层

页面路由、表格类型与设置、controlConfiguration、视图、标题/页脚、自定义片段挂载点

app/listreport-objectpage/webapp/manifest.json、app/worklist/webapp/manifest.json 等

高

扩展层

注解表达不了的前端零件:自定义列、自定义筛选器、自定义分面、自定义操作、自定义对象页

app/<应用>/webapp/ext/ 下的 XML fragment(片段)与 TypeScript 控制器扩展

按需

运行时

UI5 + Fiori elements 模板(ListReport、ObjectPage、FPM)

不直接改,由服务元数据 + manifest.json 驱动

不改

关键认知:这个案例里前端几乎没有手写页面代码。你看到的每个表格列、每张卡片、每个按钮,都是 SDK 里的模板在运行时根据「服务元数据里的注解 + manifest 里的页面配置」渲染出来的。所以改注解就是在改界面。

SAP CAP 服务端的欢迎页:同一个 CAP 服务既列出前端 Web 应用入口(Web Applications),也列出 OData 服务端点(Service Endpoints,含 /processor 的元数据与服务端点,以及各实体集的 Fiori preview 链接);本案例的 /srv1 服务与前端静态资源同样由同一个 CAP 进程提供(SAP 官方课程 UX405 示意图,非本案例截图)

一条请求的完整链路

  1. 浏览器打开应用,UI5 引导程序加载 manifest.json(应用描述文件)。

  2. manifest.json 的 sap.app/sap.ui5 决定数据源(/srv1 这个 OData V4 服务)、页面路由和每个页面的 entitySet、tableSettings、controlConfiguration。

  3. Fiori elements 模板向服务请求 $metadata;CAP 在编译时把 CDS 里的注解翻译成 OData 注解,随 $metadata 一起返回。

  4. 模板读取注解:UI.LineItem → 表格列;UI.FieldGroup → 表单;UI.Facets → 对象页分节;UI.HeaderInfo → 标题;UI.Identification → 按钮……

  5. 用户点按钮触发 action,请求打到 CAP;srv/list-report-srv.js 里的事件处理器执行业务逻辑。

  6. 如果 action 上声明了 @Common.SideEffects,界面在调用完成后自动刷新受影响字段。

  7. 你改注解 → cds watch 重新编译服务并重启 → 浏览器刷新拿到新 $metadata → 界面跟着变。

OData V4 请求 URL 的三段结构:service root URL + resource path + query options,例如在 SampleService.svc/Categories(1)/Products 后面再拼 top、orderby 这类查询选项;本案例向 /srv1 请求 metadata、实体集以及带 select、expand、filter 参数的查询时都按这个结构拆解(SAP 官方课程 UX405 示意图,非本案例截图)

注解是怎么变成界面的(词汇表映射)

Fiori elements 认的是一套 OData 词汇表(vocabulary)。本案例用到的主要映射如下,记住这张表,后面看代码就不会迷路:

注解

渲染成什么

UI.LineItem

表格的列定义(列表报表、对象页表格都用它)

UI.FieldGroup

表单/字段组;也可作为「一列多字段」的列来源

UI.Facets / UI.HeaderFacets

对象页内容区分节 / 标题区分面

UI.HeaderInfo

对象页标题、副标题、类型名、图标

UI.Identification

对象页标题区按钮(含底部工具栏的决定式操作)

UI.DataPoint

单个数据点:评分、进度、键值、微图的数据源

UI.Chart

微图或图表分节的类型、维度、度量

UI.SelectionFields

筛选栏默认显示哪些字段

UI.SelectionVariant / UI.SelectionPresentationVariant

视图:一组筛选条件(+排序/呈现方式)

UI.Hidden / UI.HiddenFilter / UI.PartOfPreview

隐藏分面字段 / 隐藏筛选字段 / 折叠预览

UI.Criticality / UI.ValueCriticality

行高亮、颜色、语义着色

Common.Text / Common.TextArrangement

用名称替换 ID 显示(TextOnly / TextFirst / TextLast / TextSeparate)

Common.SemanticKey

语义键:字段加粗显示

Common.ValueList / ValueListWithFixedValues

值帮助:对话框 / 下拉框 / 单选按钮

Common.IsActionCritical

关键操作:点击前弹确认框

Common.SideEffects

操作完成后刷新哪些字段

Capabilities.*

能力约束:CRUD、必填筛选、大小写不敏感、排序/筛选限制

Communication.*

联系人卡片、地址分面、邮箱/电话链接

Measures.*

金额/数量/百分比附带单位和小数位

Aggregation.* / Analytics.*

图表分节所需的分组与聚合能力

HTML5.LinkTarget

链接的打开方式(如 _blank)

Core.Immutable / Core.OperationAvailable

创建时必须填写 / 操作是否可用

SAP Fiori elements 的职责分层:Floorplans(List Report、Object Page 等页面骨架)由 Fiori elements 框架提供;应用开发者提供 OData service 与 Annotations,把业务语义映射成界面;Configuration 与 Custom code 都是可选项——这正是本案例「注解在中间、前端几乎不写代码」的分工示意(SAP 官方课程 UX405 示意图,非本案例截图)

注解文件是怎么组织的(annotations.cds 的结构)

仓库把注解按主题拆成多个 .cds 文件放在应用目录下,而不是塞进一个巨型文件。你 clone 下来后会看到大致这样的组织(文件名为源码里明确引用过的,具体以你本地仓库为准):

文件

负责的注解

典型内容

annotations.cds(应用级汇总入口,若存在)

通用注解

@odata.draft.enabled、UI.HeaderInfo、页面级组合

layouts_RootEntities.cds

根实体的页面布局

UI.LineItem、UI.Identification、UI.DataPoint、UI.Chart、UI.FieldGroup

layout.cds

列表报表/对象页的通用布局

UI.SelectionFields、UI.FilterFacets、UI.PresentationVariant

labels.cds

字段标签与显示语义

@title、@Common.Text、@Common.TextArrangement、@UI.IsImageURL、@Measures.*

value-helps.cds

值帮助

@Common.ValueList、依赖筛选、固定值列表

capabilities.cds

能力约束

Capabilities.FilterRestrictions、DeleteRestrictions、UpdateHidden、CreateHidden、FilterFunctions

field-control.cds

字段显隐

@UI.HiddenFilter、@Common.FilterDefaultValue

app/worklist/annotations.cds

Worklist 应用的注解

分析表格、选择变式等

注解语法只有三条规则要记牢:

  1. 属性注解(attribute annotation):annotate <target> with @( 注解 : 值, ... );——一条语句给 target 挂多个注解;

  2. 元素注解(element annotation):annotate <target> { 字段 @注解 : 值; ... };——针对实体里的某个字段;

  3. target 决定生效范围:写在 srv.<Entity> 上,服务元数据才会带上这条注解;写在 schema./persistence. 实体上只影响模型层,服务投影不一定暴露。拿不准时优先改 srv. 开头的语句。

两个高频语法点:

  • qualifier(限定名):同一个实体可以挂多个同类注解,用 #名称 区分,例如 UI.FieldGroup #HeaderData、UI.Chart #radialChart、UI.SelectionVariant #variant1。引用时写 '@UI.FieldGroup#HeaderData';manifest 里引用时写全路径 com.sap.vocabularies.UI.v1.SelectionVariant#variant1。

  • $Type 字段:UI.LineItem、UI.Facets 这类数组里的每个元素必须显式声明类型,如 UI.DataField、UI.DataFieldForAction、UI.DataFieldForAnnotation、UI.DataFieldForIntentBasedNavigation、UI.DataFieldWithUrl、UI.ReferenceFacet、UI.CollectionFacet。漏写 $Type 是「注解不生效」最常见的原因之一。

一个把页面结构串起来的缩略示例(真实文件里的注解分散在多个文件中,这里只示意组合关系):

// 1) 对象页标题:@UI.HeaderInfo
annotate srv.RootEntities with @(
    UI.HeaderInfo : {
        TypeName       : '{i18n>RootEntities}',
        TypeNamePlural : '{i18n>RootEntities.typeNamePlural}',
        Title          : { $Type : 'UI.DataField', Value : field },
        Description    : { $Type : 'UI.DataField', Value : description },
        ImageUrl       : imageUrl,
        TypeImageUrl   : 'sap-icon://sales-order',
    },
);

// 2) 表格列:@UI.LineItem(数组元素必须写 $Type)
annotate srv.RootEntities with @(
    UI.LineItem : [
        { $Type : 'UI.DataField', Value : imageUrl, @UI.Importance : #High },
        { $Type : 'UI.DataField', Value : field },
        { $Type : 'UI.DataFieldForAnnotation', Target : '@UI.DataPoint#ratingIndicator' },
        {
            $Type  : 'UI.DataFieldForAction',
            Action : 'LROPODataService.changeCriticality',
            Label  : '{i18n>changeCriticality}',
        },
    ],
);

// 3) 对象页分节:@UI.Facets + @UI.FieldGroup
annotate srv.RootEntities with @(
    UI.Facets : [
        { $Type : 'UI.ReferenceFacet', Target : '@UI.FieldGroup#ShowWhenInEdit', Label : '{i18n>ShowWhenInEdit}' },
        { $Type : 'UI.ReferenceFacet', Target : 'childEntities1/@UI.LineItem', Label : '{i18n>children}' },
    ],
    UI.FieldGroup #ShowWhenInEdit : {
        Data : [
            { Value : field },
            { Value : fieldWithCriticality, Criticality : criticality_code },
        ],
    },
);

注解、manifest、ext 三者的分工

你想改的东西

应该改哪里

判断依据

表格显示哪些列、列的顺序/重要性

UI.LineItem(注解)

与数据语义相关

筛选栏出现哪些字段、筛选分组、值帮助

UI.SelectionFields、UI.FilterFacets、Common.ValueList

与业务字段语义相关

表格类型、多选、行内创建、全屏、导出、多视图

manifest.json 的 tableSettings / views

属于控件行为设置,不是数据语义

对象页有哪些分节、每节什么内容

UI.Facets + UI.FieldGroup / UI.Chart / 子实体 UI.LineItem

页面结构

对象页标题、副标题、图标、标题区分面

UI.HeaderInfo、UI.HeaderFacets

页面标题结构

按钮(标准操作、决定式操作、导航)

UI.Identification / UI.LineItem 里的 DataFieldForAction

数据字段驱动

自定义列/分面/筛选器/操作的挂载

manifest.json 的 controlConfiguration / content + ext/ 片段

需要手写 XML/TS

完全自定义的对象页

manifest.json 的 target(sap.fe.core.fpm)+ XML 视图

标准模板撑不住了

为什么「改注解 → 刷新」这条循环成立,以及它会在哪里失效

cds watch 监听 CDS 文件变化,改完保存后 CAP 会重新编译模型、重启服务;Fiori elements 每次页面加载都重新读 $metadata,所以刷新浏览器就能看到新界面。注意三个失效点:

  1. 没用 watch 模式:用 npm run start 启动的是普通服务,改文件不会自动重编译,需要重启进程;

  2. 浏览器缓存了旧元数据:普通刷新可能拿缓存,用硬刷新(macOS Cmd+Shift+R,Windows Ctrl+Shift+R);

  3. 注解写在服务看不到的 target 上:比如写在了 schema./persistence. 实体,而服务投影没有暴露该字段——此时语法没错,但界面不会有任何变化。

准备工作

环境与账号

项目

要求

用途 / 说明

Node.js

LTS 版本(推荐 20.x 或更新)

CAP 与 UI5 工具链都依赖;版本过旧会在 npm ci 阶段报错

npm

随 Node 安装(9 以上)

安装依赖

Git

任意近两年版本

克隆仓库、回滚实验改动

浏览器

Chrome / Edge / Firefox 最新版

打开 Fiori 应用;调试看 Network/Console

@sap/cds-dk

可选,npm i -g @sap/cds-dk

提供 cds 命令;仓库本地依赖里通常也有,可用 npx cds 调用

VS Code + SAP Fiori tools

可选,强烈推荐

提供 Application Modeler、注解提示、片段向导

SAP Business Application Studio

可选

不想本地装 Node 时用云端开发空间

BTP 试用账户 + CF CLI + Cloud MTA Build Tool

可选,仅部署时用

步骤 11 部署到 Cloud Foundry 才需要

不需要的东西:不需要 SAP S/4HANA 或任何 ABAP 系统,不需要 BTP 账号,不需要 Fiori 启动板——本地一个 Node 进程就能把整套应用跑起来,因为数据是 CAP 内置的示例数据(SQLite)。

开始前的检查清单

  • node -v 输出 v18 或更高(推荐 v20+);

  • npm -v 输出 9 或更高;

  • git --version 正常;

  • 本机 4004 端口空闲(lsof -i :4004 无输出;Windows 用 netstat -ano | findstr 4004);

  • 能访问 GitHub 与 npm registry(公司网络需要代理时先配好 npm config set proxy);

  • 浏览器可开无痕窗口(避免旧缓存干扰);

  • 能读懂 CDS 的 annotate ... with @(...) 语法(不熟的话先花 10 分钟看 CAP 文档的 CDS 注解一节)。

三个自测问题,答不上来就先补背景再往下做:

  1. annotate srv.RootEntities with @( UI.LineItem : [...] ); 和 annotate srv.RootEntities { field @UI.Hidden; }; 有什么区别?

  2. @UI.FieldGroup #HeaderData 里的 #HeaderData 是干什么用的?引用它时路径怎么写?

  3. 为什么把 @UI.LineItem 写在 persistence.RootEntities 上,界面可能完全不认?

拉取仓库并安装依赖

git clone https://github.com/SAP-samples/fiori-elements-feature-showcase.git
cd fiori-elements-feature-showcase
npm ci

说明:

  • 仓库带 package-lock.json 时用 npm ci(按锁文件精确安装,可复现);没有锁文件时改用 npm install;

  • 第一次安装依赖需要几分钟,npm ci 报网络错误就重试或换 registry 镜像;

  • 不要用 sudo npm,也不要混用多个 Node 版本管理器,否则原生依赖可能装坏;

  • 安装完可以先确认依赖树:npm ls @sap/cds --depth=0,能打印出版本号即可。

验证。 node_modules/ 目录存在,package-lock.json 没有被意外改动(git status 干净),说明依赖装好了。此时仓库里已经能看到前面架构一节列出的注解文件:app/listreport-objectpage/ 下的 layout.cds、layouts_RootEntities.cds、labels.cds、value-helps.cds、capabilities.cds,以及各应用 webapp/manifest.json。建议先用编辑器的「在文件夹中查找」把 Search-Term、#Draft、UI.LineItem 各搜一遍,对代码分布有个印象。

操作步骤

步骤 1:启动应用,确认服务与页面都活着

做什么。 先把「服务能跑」和「页面能开」这两件事分开确认。这个仓库是一个 CAP 项目:后端服务负责 OData V4 与示例数据,前端是已经构建好的 UI5 应用。启动后 CAP 会同时提供服务和前端静态资源,所以一个进程就够了。

怎么操作。 在仓库根目录执行:

#方式 A:按仓库脚本启动(README 的主路径)
npm run start

#方式 B:开发模式启动,改 CDS 文件后自动重编译(做实验必须用这个)
npx cds watch

两种方式的区别:npm run start 适合「只跑一次看效果」;cds watch 会监听 db/、srv/ 和注解文件的改动并自动重启服务,是本教程「改注解看效果」回路的前提。端口被占用时加 --port 4005。

验证。 终端出现类似下面的输出(不同 CAP 版本措辞略有差异,关键是 listening on 和 4004):

[cds] - serving LROPODataService { path: '/srv1' }
[cds] - server listening on { url: 'http://localhost:4004' }

浏览器打开 http://localhost:4004:先看到 CAP 的欢迎页(服务端首页),页面上会列出 /srv1 这个 OData 服务端点,以及可进入的前端应用入口。点入口进去,应该能看到本教程开头那张 List Report。如果欢迎页没有直接的应用链接,就按仓库 README 的「How to run」一节点开对应 URL(不同版本的入口路径可能不同,以你本地实际为准——判断标准是能看到带 SAP 启动栏和筛选栏的 Fiori 页面,而不是 404)。

步骤 2:建立「官方文档 ↔ 代码 ↔ 界面」的特性地图

做什么。 官方原文按 8 个分节讲特性,仓库代码按文件组织,界面按页面组织。先花 15 分钟把三张地图对上,后面改注解时才知道去哪儿找。

怎么操作。 对照下表认识 8 个分节各自落在哪个页面、哪个区域:

官方分节

页面 / 区域

主要代码位置(源码中明确引用过)

本教程对应

通用特性

全局:灵活列布局、草稿、标准文本替换、自定义操作、默认排序筛选

各应用 manifest.json、annotations.cds

步骤 4、5

列表报表 · 标题区域

List Report 的筛选栏

layout.cds、value-helps.cds、capabilities.cds、field-control.cds

步骤 5

列表报表 · 内容区域

List Report 的表格

layouts_RootEntities.cds、labels.cds、capabilities.cds

步骤 6

对象页 · 通用特性

Object Page 的字段语义

labels.cds、annotations.cds

步骤 7

对象页 · 标题区域

Object Page 的标题、分面、操作

layouts_RootEntities.cds、manifest.json

步骤 7

对象页 · 内容区域

Object Page 的分节、表单、表格、图表

layouts_RootEntities.cds、manifest.json、ext/

步骤 8

底部工具栏

Object Page 的 footer bar

layouts_RootEntities.cds、manifest.json

步骤 9

自定义对象页 / 工作清单

Custom Object Page、Worklist

manifest.json、ext/view/

步骤 9

再记一类「搜索词」:原文每个特性都标了一个可在仓库里搜到的关键词(有的写在代码注释里,形如 //Search-Term: #SideEffect)。这是最快定位代码的方式,比翻目录快得多:

区域

高频搜索词

能定位到什么

全局

#Draft、enhanceI18n、CustomActions、#EditFlowAPI

草稿开关、标准文本替换、自定义操作、Edit-flow API

筛选

#FilterDefault、#HideFilter、#FilterGrouping、#VisibleFilters、#ValueHelps、#DependentFilter、#RequiredFilter、#SemanticDateFilter、#CaseInsensitiveFiltering、customFilter

默认值、隐藏、筛选分面、默认选字段、值帮助、依赖筛选、必填、语义日期、大小写不敏感、自定义筛选器

表格操作

#UnboundAction、#BoundAction、#SideEffect、#ValueHelpParameter、#ParameterDefaultValue、MenuActions、#DynamicCRUD、#NavAction、#CriticalAction、MessageToast

绑定/未绑定操作、副作用、参数值帮助、参数默认值、菜单按钮、动态 CRUD、导航按钮、关键操作、消息提示

表格与视图

tableSettings、#TreeTable、#multipleViews、quickVariantSelection、#SVariant、#SPVariant、#CreationDialog、#DefaultSort、selectionMode

表格类型、树表格、多视图、选择变式、选择呈现变式、新建对话框、默认排序、多选

表格显示

#SemanticKey、#LineItemHighlight、#RatingIndicator、#ProgressIndicator、#ToolTip、#MicroChart、#Contact、#QuickView、#MultiFieldsCol、#Image、#Units、#Link、#CustomColumn

语义键、行高亮、评分、进度、工具提示、微图、联系人、快速查看、多字段列、图片、单位、链接、自定义列

对象页

#HeaderInfo、#HeaderFacets、#ODataConcat、#DataPoint、#OPMicroChart、#OPHeaderAction、#OPTableTitle、#ConnectedFields、#ChartSection、#DeterminingAction

标题、标题分面、动态标题、数据点、微图、对象页操作、表格标题、关联字段、图表分节、决定式操作

验证。 在编辑器里用「在文件夹中查找」分别搜 Search-Term、#HeaderInfo、UI.LineItem,三秒内能找到对应文件;再用 grep -rn "Search-Term" app | head 确认搜索词确实写在代码注释里。找不到某个词也别慌——官方原文的搜索词指向仓库的文档站内搜索,本地代码里不是每个都带注释,按表里的文件位置找即可。

步骤 3:认识界面——把截图拆成 12 个特性区域

做什么。 在动手改之前,先建立「这个像素由哪条注解负责」的映射。本案例唯一一张真实成品截图就是「你会做出什么」一节那张 List Report,信息密度足够拆出十几个特性;本教程另配了 10 张 SAP 官方课程 UX405 的同类界面示意图,只用来帮助理解特性,不是本案例截图。

怎么操作。 打开应用后对照截图逐区观察,把下表填成你自己的笔记:

界面区域

截图中你看到的

背后的注解 / 配置

对应特性

SAP 启动栏

返回箭头、SAP 标志、FE feature showcase、搜索、用户头像

部署形态/启动板配置,应用本身不控制

集成方式

标题行左侧

Standard 加下拉箭头

变式管理(Variant Management)默认启用

保存筛选与表格个性化

标题行右侧

Custom action 带外链图标

content.header.actions 自定义操作,或标题区分面里的导航操作

自定义操作 / 导航

筛选栏 · 搜索

Search 输入框

列表报表标配

全文搜索

筛选栏 · 编辑状态

Editing Status: All 下拉

草稿(draft)启用后自动出现

@odata.draft.enabled

筛选栏 · 语义键

Field with semantic key 输入框

UI.SelectionFields + Common.SemanticKey

语义键筛选

筛选栏 · 货币

Property with currency + 值帮助图标

Measures.ISOCurrency + Common.ValueList

带单位字段/值帮助

筛选栏 · 评分

Rating filter 四颗星 + 重置图标

controlConfiguration 自定义筛选器 + XML 片段

自定义筛选器

筛选栏 · 操作

Go、Adapt Filters (1)

默认筛选/适配筛选

liveMode 关闭时才有 Go

视图标签行

4 个标签:SelectionVariant(Criticality between 0 and 2)(2)、SelectionVariant(Positive criticality)(2)、SelectionPresentationVariant(Criticality larger 0)(3)、View with other entity set(Criticality between 0 and 3)(4)

views.paths + UI.SelectionVariant#… / UI.SelectionPresentationVariant

多表格模式、选择变式、另一实体集

表格标题行

Root entities + 两个分段按钮(SelectionVariant…(2) / SelectionVariant…(0))

quickVariantSelection + showCounts

单表格多视图

操作工具栏

Show Details、criticalAction、Custom action、Menu Button、Create、Delete、… 溢出菜单

UI.LineItem 的 DataFieldForAction、Common.IsActionCritical、content 自定义操作、MenuActions、Capabilities.* 动态 CRUD

操作体系

表格列

Image、Field with semantic key(加粗)、Property with currency(300 JPY / 400.00 EUR)、Field with tool tip、Bullet chart、Child entity 2 (1..1)、Admin data (field group)、Radial chart

UI.IsImageURL、Common.SemanticKey、Measures.ISOCurrency、UI.DataPoint+Common.QuickInfo、UI.Chart#…、快速查看分面、UI.FieldGroup+UI.DataFieldForAnnotation、径向微图

表格显示特性

行与行首

红色竖条、勾选框、Root entity 2 with update not possible 等语义键文本

UI.LineItem.@UI.Criticality、selectionMode: "Multi"、后端示例数据

行高亮、多选、动态 CRUD 观察样本

行末尾

购物车图标按钮、> 箭头

行内 DataFieldForIntentBasedNavigation、标准行导航

导航按钮、进对象页

验证。 点一遍这些区域,确认你至少能说出 5 个区域「大概由哪类注解控制」。点行末的 > 进对象页——这就是步骤 7、8 要拆的另一个页面。官方原文没有给对象页截图,所以对象页部分请以你自己屏幕上的实际界面为准,本教程不会用编造的图冒充。

步骤 4:搭好「改注解 → 刷新 → 观察」的实验回路

做什么。 这个案例的价值不在「看完」,而在每次只改一个注解、观察一个变化。先把实验流程固定下来,后面每节都按这个流程做。

怎么操作。

  1. 用 watch 模式启动:npx cds watch,保持终端窗口可见。

  2. 定位注解:用步骤 2 的搜索词或文件表,在 app/listreport-objectpage/*.cds、app/worklist/annotations.cds、app/*/webapp/manifest.json 里找。

  3. 只改一处,保存。观察终端:CAP 会打印模型重编译/服务重启的日志。

  4. 硬刷新浏览器(macOS Cmd+Shift+R,Windows Ctrl+Shift+R),对比变化。

  5. 记录并回滚:git diff 看清自己改了什么,确认结论后用 git restore <文件> 还原;想保留就单独建分支提交。

建议建一张实验记录表,每改一处填一行:

时间

文件

改前

改后

预期

实际

是否回滚

10:05

labels.cds

字段默认标签

加了 @title

列头文字变成新标签

一致

是

三个热身实验(每个 3 分钟,改完就回滚):

实验 A:改列头文字。在 labels.cds 里找到 field 对应的属性,给它加 @title:

annotate srv.RootEntities with {
    field @title : 'My semantic key column';
}

预期:表格里原来显示语义键的那一列,列头变成 My semantic key column。

实验 B:隐藏一个筛选字段。给某个已出现在筛选栏的字段加 @UI.HiddenFilter:

annotate srv.RootEntities {
    fieldWithURLtext @UI.HiddenFilter;
}

预期:筛选栏(以及 Adapt Filters 对话框)里不再出现该字段;表格列不受影响。注意它和 @UI.Hidden 的区别:前者只隐藏筛选,后者连分面/字段一起隐藏。

实验 C:关掉变式管理。在 app/listreport-objectpage/webapp/manifest.json 的 List Report 配置里,把 variantManagement 设成 "None":

"RootEntityListReport": {
    "options": {
        "settings": {
            "variantManagement": "None",
            "entitySet": "RootEntities"
        }
    }
}

预期:标题行的 Standard 下拉消失,改为显示应用标题(可用 sap.app.subTitle 自定义)。对比截图里「Standard + 下拉」的位置,你能直观看到变式管理的存在感。

验证。 三次实验都看到预期变化、且都已回滚(git status 干净),说明回路可靠。此后每节末尾的「改注解看效果」小表都可以照此操作。

步骤 5:List Report 标题区——把筛选器体系一次讲透

做什么。 筛选栏是列表报表最常被定制的部分。本节覆盖:变式管理、副标题、实时模式、默认筛选字段、筛选分面、默认值、隐藏筛选、必填筛选、语义日期、大小写不敏感、值帮助(对话框/下拉/单选)、依赖筛选、导航属性筛选、自定义筛选器、标题区自定义操作。

怎么操作。

5.1 变式管理与标题。 变式管理默认开启(截图里的 Standard 下拉就是它),保存筛选设置与表格个性化。"variantManagement": "None" 关闭它;关闭后显示应用标题,可在 sap.app.subTitle 里换成自定义名称,文本放 i18n/i18n.properties:

"sap.app": {
    "subTitle": "{{appSubTitle}}"
}

SAP 官方课程的 List Report 楼层图:标题行左侧是 Standard 变式下拉,筛选栏含 Search、Editing Status、Category、Supplier、Preferred Product、Adapt Filters(1) 与 Go,表格工具栏有 Create / Delete 等标准操作,行末的 > 用来进对象页;与步骤 3 拆解的本案例列表报表结构一一对应(SAP 官方课程 UX405 示意图,非本案例截图)

5.2 实时模式。 把 liveMode 设为 true,筛选栏的 Go 按钮消失,输入即应用筛选:

"RootEntityListReport": {
    "options": {
        "settings": {
            "liveMode": true
        }
    }
}

5.3 默认显示哪些筛选字段。 用 UI.SelectionFields 指定字段数组,数组里的字段默认出现在筛选栏:

annotate srv.RootEntities with @(
    UI.SelectionFields : [
        field,
        fieldWithPrice,
        criticality_code,
    ],
);

5.4 筛选分组(Filter Facets)。 字段多时,用 UI.FilterFacets 把属性组织进分组,分组内容来自 UI.FieldGroup:

annotate srv.RootEntities with @(
    UI.FilterFacets : [
        { Target : '@UI.FieldGroup#chartData', Label : '{i18n>chartData}' },
        { Target : '@UI.FieldGroup#location',  Label : '{i18n>location}' },
    ],
    UI.FieldGroup #chartData : {
        Data : [
            { Value : integerValue },
            { Value : targetValue },
            { Value : forecastValue },
            { Value : dimensions },
        ],
    },
);

5.5 默认值、隐藏、必填、语义日期、大小写不敏感。 这五类都属于「筛选字段的行为」,常用注解如下:

需求

注解 / 配置

写在哪

预期效果

给筛选字段设默认值

@Common.FilterDefaultValue

field-control.cds

打开页面时筛选字段预填;不支持复杂值,复杂场景用 UI.SelectionPresentationVariant

隐藏某个筛选字段

@UI.HiddenFilter

字段上

筛选栏和 Adapt Filters 都不显示

指定必填筛选字段

@Capabilities.FilterRestrictions.RequiredProperties : [ stringProperty ]

capabilities.cds

不填就点不了 Go / 报校验错误

日期字段启用语义日期

@Capabilities.FilterRestrictions.FilterExpressionRestrictions

capabilities.cds

日期筛选出现 Today/Yesterday/From-To/Year To Date 等选项

关闭语义日期

manifest useSemanticDateRange: false

表格 controlConfiguration

回到普通日期选择;默认值为 true

语义日期默认值

manifest filterFields.<字段>.settings.defaultValues

同上

打开即按 LASTYEARS 等算子预筛

大小写不敏感筛选

@Capabilities.FilterFunctions : [ 'tolower' ]

服务级(annotate LROPODataService)

对筛选栏、表格个性化筛选、值帮助内筛选同时生效

关键代码(语义日期,注意 AllowedExpressions 取 SingleValue 或 SingleRange):

annotate srv.RootEntities with @(
    Capabilities.FilterRestrictions : {
        RequiredProperties : [ stringProperty ],
        FilterExpressionRestrictions : [
            { Property : 'validFrom', AllowedExpressions : 'SingleRange' }
        ],
    },
);
// 大小写不敏感:标在服务上,对整个服务生效
annotate LROPODataService with @(
    Capabilities.FilterFunctions : [ 'tolower' ],
);

5.6 值帮助(Value Help)。 CAP 对代码列表(Code List)开箱即有值帮助,其他关联要手工标 @Common.ValueList。先看最常用的「对话框值帮助」:

annotate schema.RootEntities with {
    contact @(Common : {
        Text            : contact.name,
        TextArrangement : #TextOnly,
        ValueList       : {
            Label          : '{i18n>customer}',
            CollectionPath : 'Contacts',
            Parameters     : [
                {
                    $Type             : 'Common.ValueListParameterInOut',
                    ValueListProperty : 'ID',
                    LocalDataProperty : contact_ID
                },
                { $Type : 'Common.ValueListParameterDisplayOnly', ValueListProperty : 'country_code' },
                { $Type : 'Common.ValueListParameterDisplayOnly', ValueListProperty : 'city' }
            ]
        }
    });
};

三种形态的升级路径:ValueListWithFixedValues 把对话框变下拉框;再加上 ValueListWithFixedValues.@Common.ValueListShowValuesImmediately 就渲染成单选按钮(默认纵向,可用 manifest 的 radioButtonsHorizontalLayout 改横向)。目前只有页面字段支持单选按钮,操作对话框里的字段还不支持。

5.7 依赖筛选与常量筛选。 典型场景:地区值帮助只显示所选国家下的地区。做法是用 ValueListParameterIn 把头部实体的 country_code 映射到地区实体的 country_code,再用 ValueListParameterFilterOnly 只做过滤不显示:

annotate schema.RootEntities with {
    region @(Common : {
        Text            : region.name,
        TextArrangement : #TextFirst,
        ValueListWithFixedValues : true,
        ValueList       : {
            Label          : '{i18n>Region}',
            CollectionPath : 'Regions',
            Parameters     : [
                { $Type : 'Common.ValueListParameterInOut', ValueListProperty : 'code', LocalDataProperty : region_code },
                { $Type : 'Common.ValueListParameterOut',   ValueListProperty : 'name', LocalDataProperty : region.name },
                { $Type : 'Common.ValueListParameterFilterOnly', ValueListProperty : 'country_code' },
                { $Type : 'Common.ValueListParameterIn',    LocalDataProperty : country_code, ValueListProperty : 'country_code' }
            ]
        }
    });
};

固定常量筛选用 Common.ValueListParameterConstant,例如只显示 DE 的地区:

{
    $Type               : 'Common.ValueListParameterConstant',
    ValueListProperty   : 'country_code',
    Constant            : 'DE',
}

带值帮助的多输入字段(给根实体分配多个地区)用 LocalDataProperty : root.country_code 引用父实体属性,值帮助本身标注在分配实体的字段上。

5.8 导航属性筛选。 把导航路径直接加进 @UI.SelectionFields:

annotate srv.RootEntities with @(
    UI.SelectionFields : [
        childEntities1.criticalityValue_code
    ],
);

如果想让它出现在 Adapt Filters 对话框的独立分面里,还要在 manifest 里登记:

"controlConfiguration": {
    "@com.sap.vocabularies.UI.v1.SelectionFields": {
        "navigationProperties": [ "childEntities1", "Order/decimalProperty" ]
    }
}

只写关联名 → 该关联所有字段进一个独立筛选分面;写具体属性路径 → 只把该属性加进 Adapt Filters。

5.9 自定义筛选器。 数据值格式特殊(如星级评分)时需要自定义筛选器。三件套:manifest 登记(名称必须与属性名一致,property 是被筛选属性,template 指向 XML 片段)、XML 片段(用 filterValues> 绑定筛选值,可指定 operator)、控制器里重置函数:

"filterFields": {
    "starsValue": {
        "label": "{i18n>customFilter}",
        "property": "starsValue",
        "template": "sap.fe.showcase.lrop.ext.CustomFilter-Rating"
    }
}
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m" xmlns:l="sap.ui.layout">
    <HBox alignItems="Center" core:require="{handler: 'sap/fe/showcase/lrop/ext/CustomFilter-Rating'}" width="100%">
        <RatingIndicator maxValue="4" class="sapUiTinyMarginBegin"
            value="{path: 'filterValues>', type: 'sap.fe.macros.filter.type.Value', formatOptions: { operator: 'GE' }}" />
        <core:Icon src="sap-icon://reset" press="handler.onReset" class="sapUiSmallMarginBegin" />
    </HBox>
</core:FragmentDefinition>
export default class RootEntityLRExtension extends ControllerExtension<ExtensionAPI> {
    onResetRating() {
        this.base.getExtensionAPI().setFilterValues("starsValue");
    }
}

5.10 标题区自定义操作。 在 manifest 的 content.header.actions 里加,press 指向控制器方法,enabled/visible 可以是布尔值、绑定表达式或函数路径,text 是按钮文字:

"CustomActionLRGlobal": {
    "press": "sap.fe.showcase.lrop.ext.CustomActions.messageBox",
    "enabled": "sap.fe.showcase.lrop.ext.CustomActions.enabled",
    "visible": true,
    "text": "{i18n>CustomActionLRGlobal}"
}

验证。 任选三条实现:① 在 UI.SelectionFields 里增删一个字段,刷新后筛选栏字段数量变化;② 给日期字段加 FilterExpressionRestrictions,点日期筛选能看到语义日期选项;③ 把 liveMode 设为 true,Go 按钮消失。三个都见到即本节过关。

步骤 6:List Report 内容区——表格、操作与多视图

做什么。 这是整个案例最大的一节:表格里能放什么(列与图)、表格上能做什么(操作)、表格怎么组织(视图)。建议按 6.1 → 6.2 → 6.3 顺序做,每组做完做一次验证再继续。

怎么操作。 改动全部落在 app/listreport-objectpage/ 下的注解文件与 webapp/manifest.json 里,偶尔涉及 ext/ 片段。下面按「操作 → 视图 → 列」三组展开,每组给出代表性代码和一个验证点。

6.1 操作体系(Actions)。 CAP 里的 action 分绑定(bound)与未绑定(unbound):绑定操作要先选中至少一条记录才能执行,未绑定操作随时可执行。要让它出现在界面,就把 UI.DataFieldForAction 加进表格的 UI.LineItem:

annotate srv.RootEntities with @(
    UI.LineItem : [
        {
            $Type : 'UI.DataFieldForAction',
            Action : 'LROPODataService.changeCriticality',   // 绑定操作:服务名.操作名
            Label : '{i18n>changeCriticality}',
        },
        {
            $Type : 'UI.DataFieldForAction',
            Action : 'LROPODataService.EntityContainer/unboundAction',  // 未绑定操作:走 EntityContainer
            Label : '{i18n>unboundAction}',
        },
    ],
);

操作体系里最容易踩的坑和对应写法:

需求

写法 / 配置

说明

操作按钮出现在表格工具栏

UI.DataFieldForAction 进 UI.LineItem

默认与其他操作并列在表格右上方

内联显示(跟内容同一行工具栏)

加 Inline : true;可再给 IconUrl 用图标代替文字

内联时图标优先

让操作只从界面消失

加 Determining : true

决定式操作在 List Report 表格不受支持,加了会直接消失(决定式操作用于对象页底部)

动态启用/禁用操作

@Core.OperationAvailable,值可用 $edmJson 表达式,如 {$edmJson: {$Path: '/Singleton/enabled'}} 或 ($self.integerValue > 0)

绑定操作可用相对绑定上下文的路径;in 指绑定上下文,不带 in 指操作参数

操作后刷新界面

在操作上加 @Common.SideEffects : { TargetProperties : ['in/integerValue'] }

需要 OData 绑定参数才能在注解里引用要刷新的字段

操作参数默认值

@UI.ParameterDefaultValue : 50

直接写在参数上

操作参数的值帮助

在参数上内联 Common.ValueList + ValueListWithFixedValues

必须与参数写在一起(内联),不能另起语句

操作收进下拉菜单

manifest controlConfiguration → LineItem.actions.MenuActions

text 是菜单标签,menu 列出操作标识;未绑定操作用 DataFieldForAction::服务.EntityContainer::操作

动态 CRUD 限制

Capabilities.DeleteRestrictions.Deletable、UI.UpdateHidden、UI.CreateHidden

值可以是字段路径、固定值或 $edmJson 指向 Singleton;UI.UpdateRestrictions 只限制可更新范围、不会隐藏 Edit 按钮,要隐藏请用 UI.UpdateHidden

关键操作(弹确认框)

@Common.IsActionCritical : true

点击前弹气泡确认框

消息提示

后端 req.notify('...')

severity=1 显示 message toast,更高 severity 显示对话框

表格工具栏自定义操作

manifest controlConfiguration.LineItem.actions.CustomActionLR

press 指向控制器方法,enabled 可用 enabledForSingleSelect 这类函数

SAP 官方课程中 List Report 表格工具栏的通用操作按钮:Accept Travel、Reject Travel、Create、Delete(图中 Create / Delete 高亮);它们和本案例的 Show Details、criticalAction、Custom action、Menu Button、Create、Delete 一样,来自 UI.LineItem 的 DataFieldForAction 与 Capabilities 动态 CRUD 配置(SAP 官方课程 UX405 示意图,非本案例截图)

几个代表性代码:

// 动态 CRUD:删除看字段、编辑/创建用 $edmJson 指向 Singleton
annotate srv.RootEntities with @(
    Capabilities.DeleteRestrictions : { Deletable : deletePossible },
    UI.UpdateHidden : updateHidden,
    UI.CreateHidden : { $edmJson : { $Path : '/Singleton/createHidden' } },
);
// 带副作用与参数默认值的操作(定义在实体上)
entity RootEntities as select from persistence.RootEntities actions {
    @(Common.SideEffects : { TargetProperties : ['in/integerValue'] })
    action changeProgress (@(title : '{i18n>newProgress}', UI.ParameterDefaultValue : 50) newProgress : Integer);
};
// 操作下拉菜单:列表报表 controlConfiguration 下
"@com.sap.vocabularies.UI.v1.LineItem": {
    "actions": {
        "MenuActions": {
            "text": "{i18n>MenuButton}",
            "menu": [
                "DataFieldForAction::LROPODataService.changeCriticality",
                "DataFieldForAction::LROPODataService.EntityContainer::unboundAction"
            ]
        }
    }
}

导航按钮(跳转到其他应用/实体)用 UI.DataFieldForIntentBasedNavigation,SemanticObject + Action 在目标应用 manifest.json 的 crossNavigation.inbounds 里定义;RequiresContext: true 表示必须先选中记录;属性名不一致时用 Mapping 把本地属性映射到语义对象属性:

{
    $Type : 'UI.DataFieldForIntentBasedNavigation',
    Label : '{i18n>IntentBasedNavigation}',
    SemanticObject : 'FeatureShowcaseOrder',
    Action : 'manage',
    RequiresContext : true,
    Inline : true,
    IconUrl : 'sap-icon://cart',
    Mapping : [
        {
            $Type : 'Common.SemanticObjectMappingType',
            LocalProperty : integerValue,
            SemanticObjectProperty : 'integerProperty',
        },
    ],
    @UI.Importance : #High,
}

6.2 表格类型与多视图。 表格类型在 manifest 的 tableSettings.type 里切换,支持 ResponsiveTable(响应式,默认)、GridTable、AnalyticalTable、TreeTable。响应式表格在窄屏下会按 @UI.Importance 决定列的优先级与去留,这也是「改 Importance 看列位置变化」的原因。

树表格(层级数据)是这一节的硬骨头,三件事必须对齐:

  1. manifest 里 type: "TreeTable",hierarchyQualifier 必须与 @Aggregation.RecursiveHierarchy 的 qualifier 一致;

  2. 层级注解指明父节点导航属性与节点标识:

annotate srv.OrganizationalUnits @Aggregation.RecursiveHierarchy #OrgUnitsHierarchy : {
    ParentNavigationProperty : superOrdinateOrgUnit,
    NodeProperty             : ID,
};
  1. CAP 还要补上 Fiori 期望的 4 个层级列并在筛选/排序上排除它们:

extend srv.OrganizationalUnits with @(
    Hierarchy.RecursiveHierarchy #OrgUnitsHierarchy : {
        LimitedDescendantCount : LimitedDescendantCount,
        DistanceFromRoot       : DistanceFromRoot,
        DrillState             : DrillState,
        LimitedRank            : LimitedRank
    },
    Capabilities.FilterRestrictions.NonFilterableProperties : [
        'LimitedDescendantCount', 'DistanceFromRoot', 'DrillState', 'LimitedRank'
    ],
    Capabilities.SortRestrictions.NonSortableProperties : [
        'LimitedDescendantCount', 'DistanceFromRoot', 'DrillState', 'LimitedRank'
    ],
) columns {
    null as LimitedDescendantCount : Int16,
    null as DistanceFromRoot       : Int16,
    null as DrillState             : String,
    null as LimitedRank            : Int16,
};

树表格的附加操作(上移/下移/复制)用 @Hierarchy.RecursiveHierarchyActions 指定绑定操作;Capabilities.UpdateRestrictions.NonUpdatableNavigationProperties : [ superOrdinateOrgUnit ] 可禁用所有层级变更(注意该限制目前 API 层未必强制执行)。新建按钮还能按节点类型给不同选项(creationMode.nodeType + createInPlace + isCreateEnabled 扩展钩子),并用 isNodeMovable、isMoveToPositionAllowed、isNodeCopyable、isCopyToPositionAllowed 精细控制拖拽。

多视图分两种模式:

  • 单表格模式:所有视图共用一个表格,用表格标题旁的分段按钮切换;需要先定义 UI.SelectionVariant,再在 manifest 里引用。注意:单表格模式只改变选中哪些数据,不能改变呈现方式(那是 SelectionPresentationVariant)或实体集。

"quickVariantSelection": {
    "paths": [
        { "annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant1" },
        { "annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant2" }
    ],
    "hideTableTitle": false,
    "showCounts": true
}
  • 多表格模式:表格上方渲染图标标签栏,每个视图有自己的表格、工具栏和(若启用)变式管理;每个视图必须唯一 key,annotationPath 指向 SelectionVariant 或 SelectionPresentationVariant;给某个条目加 entitySet 还能让该标签显示另一个实体集(此时各视图记录数自动显示,showCounts 失效):

"views": {
    "paths": [
        { "key": "tab1", "annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant1" },
        { "key": "tab2", "annotationPath": "com.sap.vocabularies.UI.v1.SelectionPresentationVariant#SelectionPresentationVariant" },
        { "key": "tab3", "entitySet": "OrganizationalUnits", "annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#activeOrgUnits" }
    ],
    "showCounts": false
}

选择变式与选择呈现变式的注解长这样(截图里第一行 4 个标签,就是这些注解的组合效果):

annotate srv.RootEntities with @(
    UI.SelectionVariant #variant1 : {
        Text : '{i18n>SVariant1}',
        SelectOptions : [
            {
                PropertyName : criticality_code,
                Ranges : [
                    { Sign : #I, Option : #BT, Low : 0, High : 2 },
                ],
            },
        ],
    },
    UI.SelectionPresentationVariant #SelectionPresentationVariant : {
        Text : '{i18n>SelectionPresentationVariant}',
        SelectionVariant : {
            $Type : 'UI.SelectionVariantType',
            SelectOptions : [
                {
                    PropertyName : criticality_code,
                    Ranges : [ { Sign : #I, Option : #GT, Low : 0 } ],
                },
            ],
        },
        PresentationVariant : {
            SortOrder : [ { Property : fieldWithPrice, Descending : false } ],
            Visualizations : [ '@UI.LineItem#simplified' ],
        },
    },
);

Option 支持的算子:EQ、BT、LE、GE、NE、GT、LT。单表格模式与多表格模式可以叠用:当多表格视图用 SelectionVariant 时,单表格的视图还能再叠加;用 SelectionPresentationVariant 时不能叠加。

6.3 表格显示特性(列)。 下表是「想要什么效果 → 加什么注解」的速查表,全部可在 layouts_RootEntities.cds / labels.cds 里找到对应实现:

需求

注解 / 配置

预期界面

新建时强制填写(创建对话框)

字段标 @Core.Immutable

新建对话框里出现该字段;因为之后不能更新,值必须创建时给

默认排序

UI.PresentationVariant(SortOrder + Visualizations: ['@UI.LineItem'])

表格按指定字段排序;未定义时升序

多选

manifest tableSettings.selectionMode: "Multi"

每行出现勾选框(截图里就有)

语义键加粗

Common.SemanticKey : [ field ]

指定字段在表格/表单中加粗(目前只对默认 DataField 生效)

行高亮

UI.LineItem.@UI.Criticality : criticality_code

每行左侧出现红/黄/绿竖条(截图第一行红条)

评分星级

UI.DataPoint(Visualization: #Rating、TargetValue: 4)+ UI.LineItem 里 DataFieldForAnnotation 指向它

列里出现星形;x.25–x.74 显示半星

进度条

UI.DataPoint(Visualization: #Progress、TargetValue: 100)+ DataFieldForAnnotation

列里出现进度条,可加 Criticality 改颜色

字段工具提示

UI.DataPoint 只写 Value + @Common.QuickInfo 文本,再挂进 LineItem

鼠标悬停字段显示提示

智能微图

UI.DataPoint + UI.Chart(ChartType: #Donut 等)+ LineItem 指向 Chart

列里出现微图(截图 Bullet chart / Radial chart)

联系人快速查看

联系人实体标 Communication.Contact,LineItem 里 Target : 'contact/@Communication.Contact'

列里显示联系人卡片入口,点开有电话/地址

快速查看分面

关联实体标 UI.QuickViewFacets(引用 UI.FieldGroup,可配 UI.HeaderInfo)

点单元格里的关联值弹出更多信息(截图 fieldValue)

一列放多个字段

定义 UI.FieldGroup,LineItem 里用 DataFieldForAnnotation 指向该 FieldGroup

响应式表格里一列多行(截图 Admin data (field group))

图片列

存 URL 的字段标 @UI.IsImageURL,作为普通 DataField 加入 LineItem

表格第一列显示图片

货币/计量单位

金额字段标 @Measures.ISOCurrency,数量标 @Measures.Unit,百分比用 @Measures.Unit : '%'

值后面带货币码/单位(截图 300 JPY、400.00 EUR),不用另加一列

自定义单位小数位

@CodeList.UnitsOfMeasure + 单位实体的键属性标 @Common.UnitSpecificScale

显示位数由单位数据决定,而不是 CDS 类型的 scale

链接列

UI.DataFieldWithUrl(Value 显示文本、Url 目标),@HTML5.LinkTarget: '_blank' 控制打开方式

单元格变成可点链接

关联属性只在个性化里可选

LineItem 里加关联属性 + manifest columns.<列ID>.availability: "Adaptation"

默认不显示,用户可在表格设置里加出来;列 ID 形如 DataField::association2one::country_code,点用 :: 代替

自定义列

manifest columns.CustomColumn(key/header/template/availability/properties/position)+ ext/ XML 片段

在指定锚点前后插入自定义内容的列

SAP 官方课程汇总的表格内微图形态:Area(面积)、Bullet(子弹)、Line(折线)、Stacked(堆叠)、Radial(径向,图中显示 40.8%)五种微图;本案例表格里的 Bullet chart、Radial chart 列与对象页的径向微图分面都由同一套 UI.DataPoint + UI.Chart 注解驱动(SAP 官方课程 UX405 示意图,非本案例截图)

几个必须贴出来的实现(评分、微图、快速查看、自定义列):

// 评分:先定义 DataPoint,再作为 DataFieldForAnnotation 挂进 LineItem
annotate srv.RootEntities with @(
    UI.DataPoint #ratingIndicator : {
        Value         : starsValue,
        TargetValue   : 4,
        Visualization : #Rating,
        Title         : '{i18n>ratingIndicator}',
        @Common.QuickInfo : 'Tooltip via Common.QuickInfo',
    },
    UI.LineItem : [
        {
            $Type  : 'UI.DataFieldForAnnotation',
            Label  : '{i18n>ratingIndicator}',
            Target : '@UI.DataPoint#ratingIndicator',
            @UI.Importance : #Low,
        },
    ],
);
// 径向微图(表格里的环形图):DataPoint + Chart + LineItem 三层引用
annotate srv.RootEntities with @(
    UI.DataPoint #radialChart : {
        Value       : integerValue,
        TargetValue : targetValue,
        Criticality : criticality_code,
    },
    UI.Chart #radialChart : {
        Title       : '{i18n>radialChart}',
        Description : '{i18n>ThisIsAMicroChart}',
        ChartType   : #Donut,
        Measures    : [ integerValue ],
        MeasureAttributes : [{
            $Type      : 'UI.ChartMeasureAttributeType',
            Measure    : integerValue,
            Role       : #Axis1,
            DataPoint  : '@UI.DataPoint#radialChart',
        }],
    },
    UI.LineItem : [
        {
            $Type  : 'UI.DataFieldForAnnotation',
            Target : '@UI.Chart#radialChart',
            Label  : '{i18n>radialChart}',
        },
    ],
);
// 快速查看分面:关联实体标 FieldGroup/HeaderInfo/QuickViewFacets,LineItem 用键属性触发
annotate srv.Orders with @(
    UI.FieldGroup #data : {
        Label : '{i18n>Order}',
        Data  : [ { Value : field2 }, { Value : integerProperty }, { Value : field4 } ],
    },
    UI.HeaderInfo : {
        TypeName       : '{i18n>Order}',
        TypeNamePlural : '{i18n>Order.typeNamePlural}',
        Title          : { $Type : 'UI.DataField', Value : '{i18n>Order}' },
        Description    : { $Type : 'UI.DataField', Value : field },
        TypeImageUrl   : 'sap-icon://blank-tag',
    },
    UI.QuickViewFacets : [
        { $Type : 'UI.ReferenceFacet', Target : '@UI.FieldGroup#data' }
    ],
);

annotate srv.RootEntities with @(
    UI.LineItem : [
        {
            $Type  : 'UI.DataField',
            Value  : association2one_ID,
            Label  : '{i18n>Order}',
            @UI.Importance : #High,
        },
    ],
);

关联属性再标 @Common.SemanticObject : 'FeatureShowcaseOrder',快速查看里还会多出「跳到相关应用」的链接。

// 自定义列:manifest 挂 XML 片段,position 指定插在哪个已有字段之后
"columns": {
    "CustomColumn": {
        "key": "customColumnLR",
        "header": "{i18n>validityPeriodLR}",
        "template": "sap.fe.showcase.lrop.ext.CustomColumn-DateRangeLR",
        "availability": "Adaptation",
        "horizontalAlign": "Center",
        "width": "auto",
        "properties": [ "validFrom", "validTo" ],
        "position": { "placement": "After", "anchor": "DataField::fieldWithCriticality" }
    }
}
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m">
    <Label text="{validFrom} - {validTo}"/>
</core:FragmentDefinition>

6.4 本节实验清单。 挑三个做,每个都要记录前后对比:

  1. 把某列的 @UI.Importance 从 #High 改成 #Low,缩小浏览器窗口,观察列被挤掉/后移的顺序变化;

  2. 仿照上面评分示例,把「Field with tool tip」那列换成评分列(复制 DataPoint + 改 LineItem 的 Target),确认星形出现;

  3. 在 manifest 里把 selectionMode 从 "Multi" 改成 "None",确认勾选框消失、依赖选中行的操作变灰。

验证。 打开表格的 … / Adapt Filters,能找到本节表格里至少 10 个特性的真实体现;改一次 Importance、一次 LineItem 元素、一次 manifest 设置,三次都按预期变化并回滚。

步骤 7:Object Page 通用特性与标题区域

做什么。 从 List Report 点行末尾的 > 进入对象页。对象页由「标题区域 + 内容区 + 底部工具栏」三部分组成,本节先把标题区域和字段语义讲透——对象页里看起来最「设计」的部分,几乎都是标题区注解的功劳。

怎么操作。

SAP 官方课程的灵活列布局(Flexible Column Layout)示意:左列 List Report 选中一行后,右列直接打开对应对象页——标题区分面依次是销售区域与净额、联系人信息、信用额度子弹微图、Items 比较图、径向微图、评分与进度,底部是 Positive / Negative / Change Order Status (Footer) 决定式操作;官方「通用特性」一节还包括灵活列布局,步骤 9.1 的底部工具栏就是同一套决定式操作(SAP 官方课程 UX405 示意图,非本案例截图)

7.1 字段语义(通用特性)。 三个高频注解:

需求

注解

写在哪

预期效果

邮箱可点

@Communication.IsEmailAddress

字段上

邮箱渲染成 mailto: 链接

电话可点

@Communication.IsPhoneNumber

字段上

电话渲染成 tel: 链接

长文本多行

@UI.MultiLineText

字段上

长字符串折行显示;行数由 manifest 的 formatOptions 控制

日期/时间显示风格

@UI.DateTimeStyle : 'short'(可选 short/medium/long/full)

日期字段上

日期按指定长度显示;不标也能显示,因为日期/时间/时间戳由数据类型开箱支持

编辑态占位符

@UI.Placeholder : 'Select a region'

字段上

输入框空值时显示灰色提示文字,值也可以是属性路径

多行文本的行数控制全部在 manifest 里(限定名就是带 @UI.MultiLineText 的数据字段):

"DataField::description": {
    "formatOptions": {
        "textLinesDisplay": 1,
        "textLinesEdit": 3
    }
},
"DataField::description_customGrowing": {
    "formatOptions": {
        "textMaxLines": "5",
        "textMaxCharactersDisplay": 400,
        "textExpandBehaviorDisplay": "Popover"
    }
}

textMaxCharactersDisplay 可设 Infinity 完整显示;textExpandBehaviorDisplay 可设 InPlace(默认,就地展开)或 Popover(弹出层展示)。

7.2 标题与副标题。 对象页标题区完全由 @UI.HeaderInfo 定义:TypeName(标题栏里 SAP Logo 旁的实体名)、TypeNamePlural(父对象页表格里显示的类型复数名)、Title(左侧粗体标题)、Description(标题下方描述)、ImageUrl(有图则显示在标题左侧)、TypeImageUrl(无图时显示的图标)。想动态拼接标题,用 odata.concat 表达式:

annotate srv.RootEntities with @(
    UI.HeaderInfo : {
        TypeName       : '{i18n>RootEntities}',
        TypeNamePlural : '{i18n>RootEntities.typeNamePlural}',
        Title          : { $Type : 'UI.DataField', Value : field },
        Description    : { $Type : 'UI.DataField', Value : '{i18n>RootEntities}' },
        ImageUrl       : imageUrl,
        TypeImageUrl   : 'sap-icon://sales-order',
    },
);
// 动态副标题:用 || 拼接,用 ? : 做条件(等价于 $If)
annotate service.ChildEntities1 with @(
    UI.HeaderInfo : {
        Description : {
            $Type : 'UI.DataField',
            Value : ('Using odata.concat - Field: ' || (field = 'child entity 1' ? field : 'Other child entities')),
        },
    },
);

7.3 标题区域分面(Header Facets)。 标题区可以放很多「小卡片」,统一由 @UI.HeaderFacets 管理,元素是 UI.ReferenceFacet 或 UI.CollectionFacet(collection facet 必须带 ID 才能工作)。常见分面:

分面类型

用到的注解

你要注意的点

纯文本

ReferenceFacet 指向 UI.FieldGroup,字段标 @UI.MultiLineText

字段组是普通 Data 数组即可

字段组

ReferenceFacet 指向 UI.FieldGroup

Data 里可用 UI.DataField 与 UI.DataFieldForAnnotation;后者可放联系人快速视图,键字段加入即可触发

自定义字段

manifest controlConfiguration.FieldGroup#HeaderData.fields + XML 片段

position.placement 取 Before/After,锚点是字段组里其他数据字段

地址

ReferenceFacet 指向 contact/@Communication.Address

地址文本来自 Communication.Address.label,换行用 \n,label 需完整格式化

数据点(键值/评分/进度)

ReferenceFacet 指向 @UI.DataPoint#…

数字数据点可覆盖 scale/precision;评分用 Visualization: #Rating,进度用 #Progress;@Common.QuickInfo 加提示

微型图表

ReferenceFacet 指向 @UI.Chart#…

分面标题=Chart 的 Title,副标题=Description;支持 Area、Bullet、Radial、Column、Line、Harvey、Stacked bar、Comparison 八种

自定义分面

manifest content.header.facets + XML 片段

template(显示模式)与 templateEdit(编辑模式,内容用 sap.ui.layout.FormElement 组织);stashed 控制是否默认隐藏、留给关键用户适配

标题区域分面的基础写法:

annotate srv.RootEntities with @(
    UI.HeaderFacets : [
        { $Type : 'UI.ReferenceFacet', Target : '@UI.DataPoint#fieldWithPrice' },
        {
            $Type : 'UI.ReferenceFacet',
            Target : '@UI.FieldGroup#HeaderData',
            Label : '{i18n>HeaderData}',
        },
        {
            $Type : 'UI.ReferenceFacet',
            Target : '@UI.FieldGroup#plainText',
            Label : '{i18n>plainText}',
        },
    ],
    UI.FieldGroup #plainText : {
        Data : [ { Value : description } ],
    },
);

SAP 官方课程中的联系人快速查看卡片:点表格里的联系人链接会弹出卡片,显示姓名(Aussie Travel)、Contact Information、电话 +44 161 2052000 与地址;本案例对象页字段组里的联系人快速视图、表格里的 fieldValue 快速查看都用同一套 Communication.Contact / UI.FieldGroup + UI.ReferenceFacet 机制(SAP 官方课程 UX405 示意图,非本案例截图)

微型图表分面在标题区出现的八种形态(决定视觉效果的是 ChartType,数据源是 UI.DataPoint):

微图类型

ChartType

DataPoint 里最关键的字段

说明

面积图

#Area

Value、TargetValue、CriticalityCalculation(必填)

趋势图;临界值计算用于着色

子弹图

#Bullet

Value、TargetValue、ForecastValue、MinimumValue、Criticality

实际值 vs 目标值;Criticality 覆盖 CriticalityCalculation;不支持 criticality=5

径向图

#Donut

Value、TargetValue、Criticality

显示百分比(Value/TargetValue)

折线图

#Line

多个 DataPoint 的 Value + Criticality

建议只用 1 个度量,最多 3 个;线色由最后一个数据点决定

柱状图

#Column

Value、Criticality

同维度垂直条比较

Harvey 图

#Pie

Value、MaximumValue、Criticality

单值对最大值;只支持 Criticality

堆叠条形图

#BarStacked

Value、Criticality

同维度垂直堆叠比较

比较图

#Bar

Value、Criticality

三个水平条比较;多余值进工具提示

7.4 标题区操作。 标题区按钮来自 @UI.Identification(数据字段数组),引用方式与表格操作一致,Criticality 只支持 0(正常)、1(红色)、3(绿色)。绑定操作会传入对象页上下文,未绑定操作不传上下文;导航操作同样可用。标题区自定义操作放 manifest 的 content.header.actions;底部工具栏的决定式操作见步骤 9。

annotate srv.RootEntities with @(
    UI.Identification : [
        {
            $Type  : 'UI.DataFieldForAction',
            Action : 'LROPODataService.changeCriticality',
            Label  : '{i18n>changeCriticality}',
            Criticality : criticality_code,
        },
    ],
);

7.5 从标题区分面导航。 数据点、评分/进度指示器、微图分面都能变成链接,分两种:

  • 页内导航:manifest 里给该分面加 navigation.targetSections,sectionId 是「应用 ID + --fe::FacetSection:: + 分面 ID」,有子分区时用 subSectionId 指定;不指定子分区则跳到第一个。分面 ID 来自 UI.Facets 里 CollectionFacet/ReferenceFacet 的 ID 属性。

  • 外部导航:先在 sap.app.crossNavigation.outbounds 里定义目标(semanticObject + action),再在分面配置里写 navigation.targetOutbound.outbound 指向该限定名。

"@com.sap.vocabularies.UI.v1.DataPoint#progressIndicator": {
    "navigation": {
        "targetSections": {
            "sectionId": "sap.fe.showcase.lrop::RootEntityObjectReport--fe::FacetSection::chartData",
            "subSectionId": "sap.fe.showcase.lrop::RootEntityObjectReport--fe::FacetSubSection::advancedChartData"
        }
    }
}

7.6 标题可编辑性、子页与 Related Apps。

  • "editableHeaderContent": false:标题区在编辑模式与显示模式下都不可编辑(默认编辑模式下可编辑);

  • 子页:在 manifest 里加一条路由(pattern + name + target)和一个 target(type: "Component"、name: "sap.fe.templates.ObjectPage"、entitySet: "ChildEntities1"),然后在对象页配置的 navigation.childEntities1.detail.route 引用路由名;

  • "showRelatedApps": true:标题区操作行出现 Related Apps 按钮,列出语义对象相同的应用。

验证。 打开对象页:标题、副标题、图标正确;至少有 3 个标题区分面;点数据点/微图分面能跳到内容区对应分节;编辑模式下邮箱/电话是链接。改一次标题文字或加一个 plain text 分面,刷新能看到变化。

步骤 8:Object Page 内容区域——分节、表单、表格与图表

做什么。 对象页的内容区由 @UI.Facets 组织成若干分节。分节在界面上有两种形态:页签(Tabs)或上下排布(Page),由 manifest 的 sectionLayout 决定。UI.CollectionFacet 是分节容器,UI.ReferenceFacet 是真正的内容(一个表单、一张表格、一个图表)。collection facet 必须带 ID;第 3 层及更深的 collection facet 不予考虑;用表格的分节建议用 Tabs 形态。

怎么操作。

SAP 官方课程的对象页楼层图:标题区有标题、副标题、分类/供应商/可用量/价格/星级等字段与 Edit / Delete / Assign Supplier 操作,下面是 General Information / Reviews 页签;内容区用 Basic Data、Technical Data、Admin Data 三个字段组表单分节与 Reviews 子实体表格分节,对应本教程步骤 7 的标题区与步骤 8 的内容区(SAP 官方课程 UX405 示意图,非本案例截图)

8.1 内容区通用特性。

需求

注解 / 配置

预期效果

用名称替换 ID 显示

@Common.Text : criticality.name + @Common.TextArrangement

显示名称而非难读的 ID;#TextOnly/#TextFirst/#TextLast/#TextSeparate 控制名称与 ID 的排布

隐藏分面/字段

@UI.Hidden(只接受布尔值,不支持 ! 表达式)

分面或字段不渲染;常用于「只在编辑模式显示」的字段组

折叠预览

@UI.PartOfPreview : false

该子分面默认收起,需要点 Show more 才展开

侧边内容

manifest content.body.sections.<限定名>.sideContent + showSideContent()

分节/子分区旁出现可切换的侧边内容;equalSplit: true 时 1:1 分屏,否则 2:1

侧边内容切换函数(参数是侧边内容出现位置的 facet 限定符):

export default class RootEntityOPExtension extends ControllerExtension<ExtensionAPI> {
    toggleSideContent() {
        this.base.getExtensionAPI().showSideContent("customSectionQualifier");
    }
    toggleSideContentItem1() {
        this.base.getExtensionAPI().showSideContent("childEntities1Section");
    }
}

8.2 表单。 表单 = 一个 UI.FieldGroup + 一个引用它的 ReferenceFacet。字段组里的普通字段只需 Value,不必写 $Type;字段的界面标签推荐在 labels.cds 里用 @title 定义(也可以用 DataField 的 Label)。字段组自己的 Label 界面不显示,显示的是 reference facet 的 Label。

annotate srv.RootEntities with @(
    UI.Facets : [
        { $Type : 'UI.ReferenceFacet', Target : '@UI.FieldGroup#ShowWhenInEdit', Label : '{i18n>ShowWhenInEdit}' },
    ],
    UI.FieldGroup #ShowWhenInEdit : {
        Data : [
            { Value : field },
            { Value : fieldWithCriticality },
            { Value : fieldWithUoM },
            { Value : contact_ID },
            { Value : association2one_ID },
        ],
    },
);

表单还能放三类「进阶内容」:

  • 关联字段:两个语义相关的字段并排显示在同一个标签下,用 @UI.ConnectedFields,Template 决定顺序与分隔符(如 '{integerValue} / {targetValue}'),Data 里每个字段的 $Type 必须是 UI.DataField,否则不渲染;只能用在表单里,表格和标题区不支持。

  • 自定义内容:manifest controlConfiguration.FieldGroup#<限定名>.fields.<ID>(label + template + position)挂 XML 片段。

  • 表单操作与导航:把 UI.DataFieldForAction / UI.DataFieldForIntentBasedNavigation 直接加进字段组的 Data 数组,默认显示在分区右上角;给数据字段加 Inline : true 则移到表单工具栏;@UI.Emphasized : true 强调按钮。

8.3 表格分节。 对象页表格最常用于子实体/关联实体,实现分两步:子实体标 UI.LineItem 定义列;根实体的 UI.Facets 里用 ReferenceFacet 指向 'childEntities1/@UI.LineItem'。表格设置全部在 manifest 的 controlConfiguration['childEntities1/@com.sap.vocabularies.UI.v1.LineItem'].tableSettings 下:

需求

manifest 配置

预期效果

变式管理

"variantManagement": "Control"

表格自己保存变式

个性化开关

"personalization": { "column": true, "sort": false, "filter": true }

分别控制列/排序/筛选能否个性化

全屏

"enableFullScreen": true

表格右上角出现全屏按钮

表格标题

来自子实体 UI.HeaderInfo.TypeNamePlural;与分区标题相同或未定义则不显示

表格上方出现标题

分段按钮切换视图

"quickVariantSelection": { "paths": [...], "showCounts": true }

3 个以上视图自动变下拉

行内创建

"creationMode": { "name": "Inline", "createAtEnd": true }

表格里直接加行;NewPage 则进新建页

导出到电子表格

"enableExport": true

导出 按钮(随复制/粘贴一起启用,默认关闭)

表格工具栏自定义操作

tableSettings 同级 actions.CustomActionOPTableToolbar

按钮可用 enabled 绑定表达式

8.4 图表分节。 内容区图表比标题区微图复杂,因为要声明聚合能力。三步:

  1. 数据源实体标 @Aggregation.ApplySupported(GroupableProperties + AggregatableProperties);

  2. 标 @Analytics.AggregatedProperties 定义支持的聚合方法(min/max/average…);

  3. 定义 @UI.Chart,Measures 写聚合方法的名字(不是实体属性名,写错图表不显示),DimensionAttributes 用 Role: #Category;最后把 UI.Chart 作为 ReferenceFacet 加进 UI.Facets(目标写成 'chartEntities/@UI.Chart')。图表工具栏操作加在 Actions 数组里;维度语义着色用 @UI.ValueCriticality 把取值映射到 #Neutral/#Negative/#Critical/#Positive。

annotate service.ChartDataEntities with @(
    Aggregation.ApplySupported : {
        GroupableProperties    : [ dimensions, criticality_code ],
        AggregatableProperties : [ { Property : integerValue } ],
    },
    Analytics.AggregatedProperties : [
        { Name : 'minAmount', AggregationMethod : 'min',     AggregatableProperty : 'integerValue', @Common.Label : 'Minimal Net Amount' },
        { Name : 'maxAmount', AggregationMethod : 'max',     AggregatableProperty : 'integerValue', @Common.Label : 'Maximal Net Amount' },
        { Name : 'avgAmount', AggregationMethod : 'average', AggregatableProperty : 'integerValue', @Common.Label : 'Average Net Amount' },
    ],
);
annotate service.ChartDataEntities with @(
    UI.Chart : {
        Title       : '{i18n>chart}',
        ChartType   : #Column,
        Measures    : [ maxAmount ],
        Dimensions  : [ dimensions ],
        MeasureAttributes : [{
            $Type   : 'UI.ChartMeasureAttributeType',
            Measure : maxAmount,
            Role    : #Axis1,
        }],
        DimensionAttributes : [
            { $Type : 'UI.ChartDimensionAttributeType', Dimension : dimensions,       Role : #Category },
            { $Type : 'UI.ChartDimensionAttributeType', Dimension : criticality_code, Role : #Category },
        ],
        Actions : [{
            $Type  : 'UI.DataFieldForAction',
            Action : 'LROPODataService.EntityContainer/unboundAction',
            Label  : '{i18n>unboundAction}',
        }],
    },
);

annotate srv.RootEntities with @(
    UI.Facets : [
        { $Type : 'UI.ReferenceFacet', Target : 'chartEntities/@UI.Chart', Label : '{i18n>chart}' },
    ],
);

8.5 自定义分区与子分区。 注解描述不了的分节,用 manifest 的 content.body.sections 挂 XML 片段:自定义分区 ID 必须唯一,template 指向片段,position(anchor + Before/After)决定插在哪个分区旁;自定义子分区放在 sections.<限定名>.subSections 里,未给 position 时放末尾,visible 支持绑定表达式。

验证。 对象页至少能看到 2 个表单分节、1 个表格分节、1 个图表分节;切换 sectionLayout 的 Tabs/Page 两种值,观察分节形态变化;打开表格的变式管理、全屏、导出按钮各一次;点图表能下钻到第二个维度。

步骤 9:底部工具栏、自定义对象页与 Worklist

做什么。 收尾三个「边角但重要」的页面特性:对象页底部操作、用 Flexible Programming Model 自定义对象页、以及 Worklist 形态。

怎么操作。

9.1 决定式操作(Determining Actions)。 这是对象页底部工具栏的主要来源:操作仍然写在 @UI.Identification 数组里,只是多一个 Determining : true。它与标题区操作的区别仅此一项。

annotate srv.RootEntities with @(
    UI.Identification : [
        {
            $Type  : 'UI.DataFieldForAction',
            Action : 'LROPODataService.changeCriticality',
            Label  : '{i18n>changeCriticality}',
            Determining : true,
            Criticality : criticality_code,
        },
    ],
);

底部工具栏也能放自定义操作:manifest 的 content.footer.actions,写法与标题区自定义操作一致(press/enabled/visible/text)。

9.2 自定义对象页(Custom Object Page)。 当标准对象页撑不住时,用 Flexible Programming Model 换掉整个子实体对象页。两步:

// 1) target:type 必须是 Component,name 必须是 sap.fe.core.fpm
"CustomObjectPage_childEntities3": {
    "type": "Component",
    "Id": "CustomObjectPageView",
    "name": "sap.fe.core.fpm",
    "options": {
        "settings": {
            "viewName": "sap.fe.showcase.lrop.ext.view.CustomObjectPage",
            "entitySet": "ChildEntities3"
        }
    }
}
// 2) route:pattern 是子对象页 URL,name 与 target 限定名一致
{
    "pattern": "RootEntities({key})/childEntities3({key2}):?query:",
    "name": "CustomObjectPage_childEntities3",
    "target": "CustomObjectPage_childEntities3"
}

自定义 XML 视图里可以用 Fiori elements 的 Building Blocks(表格、字段、分节等现成控件)来保证观感一致,不必从零画页面。

9.3 Worklist(工作清单)。 在 OData V4 里,Worklist 只是 List Report 的一种形态:列表报表的所有特性都适用,唯独筛选栏被禁用。只要在 manifest 里加一行:

"OrdersList": {
    "options": {
        "settings": {
            "hideFilterBar": true
        }
    }
}

SAP 官方课程的 Worklist 楼层图:没有筛选栏,只有应用标题、视图标签(For My Responsible Unit (83)、With My Involvement (0))与一张表格,表格里还有圆环进度微图列;本案例的 app/worklist/ 就是这种「去掉筛选栏的列表报表」形态,并额外演示分析表格与选择变式(SAP 官方课程 UX405 示意图,非本案例截图)

仓库里的 app/worklist/ 就是这样一个应用,它同时演示了分析表格、选择变式等特性,适合和列表报表对照着看。

验证。 对象页底部能看到决定式操作,点了会先弹确认(如果操作同时标了 IsActionCritical);点表格行进入自定义对象页,URL 形如 RootEntities(...)/childEntities3(...);打开 Worklist 应用,确认没有筛选栏但表格/操作/个性化都在。

步骤 10:三组综合实验——把「改注解看效果」变成肌肉记忆

做什么。 前面每节都是「单点特性」。这一节做三次综合改动,每次覆盖一个完整链路(定位 → 改 → 刷新 → 判断 → 回滚),建议严格按顺序做。

怎么操作。 三个实验相互独立,每个都先确认工作区干净(git status 无实验残留),改完立即回滚再进入下一个。

实验 1(10 分钟):给对象页加一个纯文本标题区分面。

  1. 在 layouts_RootEntities.cds 的 UI.HeaderFacets 数组里加一个 reference facet,指向新的 @UI.FieldGroup#labText;

  2. 在同文件加 UI.FieldGroup #labText : { Data : [ { Value : description } ] };

  3. 给 description 字段确认有 @UI.MultiLineText;

  4. 刷新对象页标题区。

预期:标题区多一块「纯文本」卡片,显示 description 的多行文本;如果没出现,先检查 UI.HeaderFacets 是否写在了 srv. 实体上、collection facet 是否缺 ID。

实验 2(15 分钟):切换对象页分节形态。

  1. 备份 manifest.json;

  2. 把对象页配置里的 "sectionLayout": "Tabs" 改成 "Page";

  3. 刷新对象页,上下滚动观察;

  4. 改回 Tabs。

预期:Page 形态下所有分节纵向排列,锚点栏/页签消失;Tabs 形态下每节一个页签。这个实验能让你理解「注解管内容、manifest 管形态」的分工。

实验 3(20 分钟):筛选交互三连改。

  1. 把 List Report 的 liveMode 设为 true → Go 消失,输入即筛;

  2. 把 variantManagement 设为 "None" → Standard 变式下拉消失、显示应用标题;

  3. 把 selectionMode 设为 "None" → 勾选框消失、依赖选中行的操作禁用;

  4. 逐项改回并确认界面恢复。

预期:三次改动各自只影响一个交互点,其余界面不动。如果出现「改了一项却全乱」,通常是 JSON 写坏了(漏逗号/多逗号),看浏览器 Console 的 manifest 解析错误。

验证。 三组实验均能复现、均能回滚;能把每组实验对应到「注解层/页面配置层」的分工上。

步骤 11:部署到 SAP BTP(可选)

做什么。 本地跑通就已经完成本教程的学习目标;部署只在需要把应用共享给同事、演示或做集成验证时才有必要。部署不是必做项,而且仓库的部署脚本可能随版本变化——本节给的是判断流程和验收标准,具体命令以你 clone 下来的仓库 README 的部署章节为准,不要照抄网上过时教程。

怎么操作。

  1. 确认部署形态:看仓库根目录有没有 mta.yaml。有 MTA(Multi-Target Application)描述文件,就走标准 CF 流程(mbt build → cf deploy);若仓库 README 给的是 BAS 的「Deploy」向导或其他方式,按 README 执行。

  2. 准备 BTP 环境:试用账户 → 创建 Cloud Foundry 组织/空间 → 登录(cf login -a <API 端点>)→ 按 README 要求创建并绑定数据库实例(CAP 应用通常需要 HANA Cloud/HDI 容器;README 要求什么就建什么)。

  3. 构建:确保 npm ci 成功,安装 Cloud MTA Build Tool(npm i -g mbt),在仓库根目录执行 mbt build,产物在 mta_archives/ 下(.mtar)。

  4. 部署:cf deploy mta_archives/<产物>.mtar;观察 cf logs 确认服务启动。

  5. 配置访问:如果前端与后端分开部署,按 README 在 BTP Cockpit 创建 Destination 指向服务 URL,并在 approuter 里绑定;从部署输出拿到应用路由 URL。

  6. 验证:打开云端应用,页面应与本地一致;直接访问 <服务 URL>/$metadata,能搜到 annotations 与 UI.LineItem 等注解;点几个特性确认渲染一致。

验证。 云端 List Report 能打开、能筛选、能进对象页;与本地截图对比关键区域(变式管理、筛选栏、多视图标签、表格列)一致;cf logs 无持续报错。

验收与清理

验收清单(按官方 8 个分节逐项走查,每项都要亲眼看到)。

  • 通用特性:应用能打开;草稿模式生效(编辑状态筛选存在);至少一个自定义操作可点;默认排序/筛选生效;

  • 列表报表 · 标题区:变式管理可保存变式;筛选栏有自定义筛选字段;值帮助能弹出;至少试一次依赖筛选;至少试一次语义日期或大小写不敏感筛选;

  • 列表报表 · 内容区:能看到图片列、语义键加粗、货币/单位列、快速查看、字段组列、至少一种微图;操作工具栏里绑定/未绑定操作都能点;菜单按钮能展开;动态 CRUD 按钮随选中行变化;多视图标签能切换;树表格能展开层级(如果做了);

  • 对象页 · 通用:邮箱/电话是链接;长文本多行显示;日期显示风格符合预期;

  • 对象页 · 标题区:标题/副标题正确;至少 3 个分面;至少 1 个微图分面;至少 1 个页内或外部导航;

  • 对象页 · 内容区:至少 2 个表单分节、1 个表格分节、1 个图表分节;侧边内容能切换(如果做了);自定义分区可见(如果做了);

  • 底部工具栏:决定式操作出现且点击有确认;底部自定义操作可点;

  • 自定义对象页 / Worklist:自定义对象页能进入;Worklist 无筛选栏但其余特性正常;

  • 总体验收:浏览器 Console 无红色报错;Network 里 $metadata 返回 200 且包含注解;至少完成 3 次「改注解 → 刷新 → 变化 → 回滚」并留有记录。

清理(本地实验与可选部署分别处理)。

  1. 在终端 Ctrl+C 停止 cds watch / npm run start;

  2. 回滚实验改动:git status 检查,git restore . 或按文件 git restore <文件>;想留下成果就新建分支提交,不要污染主分支;

  3. 删除本地克隆目录,或保留作为参考(建议保留,后续查特性方便);

  4. 如果做了部署:cf undeploy <应用名> --delete-services 删除应用与服务实例;删除 HANA/HDI 实例;删除为演示创建的 Destination 与角色集合;删除 BAS 开发空间(或至少停掉空间);

  5. 清理浏览器缓存:删掉 localhost:4004 的站点数据(Application → Storage → Clear site data),避免下次实验时旧 $metadata 误导判断。

常见问题

现象

原因

处理

打开 http://localhost:4004 看到的是 CAP 欢迎页,不是 Fiori 应用

你打开的是服务根路径,应用入口在另一个 URL

从欢迎页的应用入口点进去,或按仓库 README 的 URL 打开;用 4004 端口能访问服务不代表应用路径也是 /

页面 404 或一片空白

服务没启动、URL 少了应用路径、依赖没装完

看终端是否出现 listening on;重新 npm ci;用 Network 面板确认静态资源和 $metadata 请求是否 200;看 Console 第一条红字

npm ci 报错

Node 版本过旧、网络不通、registry 配置冲突

升级到 Node LTS;配置代理/镜像;删 node_modules 重来;不要用 sudo

改了注解、刷新后界面没变化

没用 watch 模式;浏览器缓存旧元数据;注解写在了服务看不到的 target 上

改用 npx cds watch;硬刷新;确认 annotate srv.<实体> 且该实体在服务里被暴露;看 $metadata 里是否出现你改的注解

注解语法没问题但 UI 完全不渲染该元素

漏 $Type;qualifier 拼写不一致;CollectionFacet 缺 ID;引用了不存在的 DataPoint/Chart

对照本文的 $Type 表逐项检查;#名字 要完全一致;collection facet 必须有 ID;被引用的注解要先定义

树表格出不来层级/报错

manifest 的 hierarchyQualifier 与 @Aggregation.RecursiveHierarchy 的 qualifier 不一致;缺 4 个层级列;未把层级列排除筛选/排序

两处 qualifier 必须同名;按步骤 6.2 补 LimitedDescendantCount/DistanceFromRoot/DrillState/LimitedRank 与对应 Capabilities 限制

评分/进度/微图列不显示

只定义了 DataPoint,没挂进 LineItem;或 Chart 未被 LineItem 引用

引用链必须是「DataPoint → LineItem 的 DataFieldForAnnotation」或「DataPoint → Chart → LineItem」;微图还要求 Measures/MeasureAttributes 齐全

自定义列/自定义分面/自定义筛选器不出现

manifest 里的 ID 与 fragment 文件名/路径不一致;template 路径少了命名空间;片段没放在 webapp 对应目录

路径格式是「应用命名空间 + fragment 在 webapp 下的路径」,如 sap.fe.showcase.lrop.ext.CustomColumn-DateRangeLR;自定义筛选器名称必须与属性名一致

操作按钮在界面上,但点击没反应或报错

未绑定操作的路径写成了 srv.xxx;绑定操作没选中上下文

未绑定操作必须写 LROPODataService.EntityContainer/<操作名>;绑定操作先选中行;看 Network 里请求的状态码与错误消息

部署后页面 404 或接口跨域失败

Destination URL/路径错;approuter 未绑定;服务未成功部署

在 BTP Cockpit 检查 destination 可达性;cf logs 查 approuter;确认 $metadata 在云端可访问;按仓库 README 的部署章节逐项核对

TypeScript 扩展编译报错

依赖未装全、TS 版本不匹配、改了类型签名

先回到纯注解实验(本教程大部分内容不需要编译扩展);重装依赖;按仓库示例文件对照签名

编辑模式相关异常(草稿、编辑状态)

草稿(draft)注解、编辑状态筛选与示例数据不匹配

确认实体已启用 @odata.draft.enabled;先按截图那样把 Editing Status 设为 All 再观察;不要在未保存草稿时切换视图对比

官方原文(参考)

本教程是官方仓库文档的中文重写与扩写:输入是 1 篇总览 + 8 篇分节文档和唯一一张应用截图;原文以「特性说明 + 注解片段」为主、几乎没有步骤截图,本教程把分散的片段按「跑通 → 认界面 → 改注解 → 逐类特性 → 验收」重组为可离线照做的流程,并补充了运行、实验回路、验收与排错。想核对原始措辞或继续深挖时,看这些页面(正文不依赖这些链接):