Fiori elements 特性全集演示 · 列表报表 · 内容区域
项目 |
内容 |
|---|---|
官方仓库 |
|
业务场景 |
用一套可运行的应用演示 Fiori elements 的每一种表格、表单与页面特性 |
技术栈 |
SAP Fiori elements for OData V4、SAPUI5、注解(annotation)、灵活编程模型 |
对应课程 |
|
对应路径 |
第 3 条 开发 SAPUI5 应用 |
为什么值得做:Fiori elements 的能力边界靠文档很难建立直觉。 这个仓库把特性做成可点开的界面,点一下就知道某个注解会产生什么效果。
动手要点:
把应用跑起来,逐个对照
annotations.cds—— 改一个注解,刷新看变化。这个「改注解看效果」的循环,是掌握 Fiori elements 最快的路径。
本页内容抓取自官方仓库 SAP-samples/fiori-elements-feature-showcase,共收录 1 篇官方文档(README 与 docs)。原仓库内容版权归 SAP SE,遵循其许可证。
Content Area List Report
配置表格
操作(Actions)
搜索词(以下关键词均可直接在官方仓库中搜索到对应示例): #UnboundAction、#BoundAction、#SideEffect、#ValueHelpParameter、"MenuActions"、#DynamicCRUD
在 CAP 中,操作(action)既可以绑定到某个具体实体,也可以不绑定、只作为服务的一部分存在。绑定操作只有在至少选中一个实体时才能执行,未绑定操作则可以随时执行。
如果希望某个操作在界面上可见,就要把 UI.DataFieldForAction 加入表格的 UI.LineItem 注解。操作通过服务调用。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAction',
Action : 'LROPODataService.changeCriticality',
Label : '{i18n>changeCriticality}',
},
...
],
);
上述注解位于 layouts_RootEntities.cds 文件中。
使用这条默认注解时,操作会显示在表格右上方,与其它可能的操作并列。如果想把操作内联显示(inline),需要加上属性 Inline : true。此外,操作内联时,可以用图标代替操作名来显示。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAction',
Action : 'LROPODataService.changeProgress',
Label : '{i18n>changeProgess}',
IconUrl : 'sap-icon://status-critical',
Inline : true,
},
...
],
);
虽然可以加上属性 Determining : true,但决定式操作(determining actions)并不被支持,加上之后操作只会从界面上消失。
上面这些操作注解针对的都是绑定操作。如果要添加未绑定操作,操作注解需要稍作调整:不要引用 srv.unboundAction,而要引用 LROPODataService.EntityContainer/unboundAction,未绑定操作才能正常工作。另一种路径写法会让操作显示在界面上,但点击时不生效。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAction',
Action : 'LROPODataService.EntityContainer/unboundAction',
Label : '{i18n>unboundAction}',
},
...
],
);
通过 @Core.OperationAvailable 可以启用或禁用操作。它的值还能用 $edmJson 动态给出,例如:
@Core.OperationAvailable: {$edmJson: {$Path: '/Singleton/enabled'}}
action unboundAction(@(title : '{i18n>inputValue}')input : String);
路径可以是绝对的(如示例中指向某个 singleton),对绑定操作也可以是相对于绑定上下文的,例如:
@(
...
Core.OperationAvailable: ($self.integerValue > 0)
)
action changeProgress (
...
);
in 指绑定上下文。不带 in 时,路径指向的是操作参数。
操作的副作用(Side Effects)
搜索词:#SideEffect
如果你的操作会触发实体数据变更,就需要副作用(side effects),让界面自动刷新。这些副作用注解要加在操作上。
entity RootEntities as select from persistence.RootEntities actions {
...
@(
Common.SideEffects : {
TargetProperties : ['in/integerValue']
}
)
action changeProgress (@(title : '{i18n>newProgress}', UI.ParameterDefaultValue : 50)newProgress : Integer);
};
需要 OData 绑定参数,才能在注解中引用实体里需要更新的字段。这些字段随后列在 @Common.SideEffects 的 TargetProperties 属性数组中。
操作参数的值帮助
实体的属性常常配有值帮助,让新建实体更容易、错误输入更少。操作参数同样可以配置值帮助。
entity RootEntities as select from persistence.RootEntities actions {
...
action changeCriticality (
@(
title : '{i18n>newCriticality}',
UI.ParameterDefaultValue : 0,
Common : {
ValueListWithFixedValues : true,
ValueList : {
Label : '{i18n>Criticality}',
CollectionPath : 'Criticality',
Parameters : [
{
$Type : 'Common.ValueListParameterInOut',
ValueListProperty : 'code',
LocalDataProperty : newCriticality
},
{
$Type : 'Common.ValueListParameterDisplayOnly',
ValueListProperty : 'name'
},
]
}
}
)
newCriticality : Integer);
...
};
做法是给参数标注一个 common valueList 注解。该注解必须与参数写在一起(内联)。
操作参数的默认值
用注解 @UI.ParameterDefaultValue 可以为参数设置默认值。
entity RootEntities as select from persistence.RootEntities actions {
...
action changeProgress (@(title : '{i18n>newProgress}', UI.ParameterDefaultValue : 50)newProgress : Integer);
};
操作下拉菜单
搜索词:"MenuActions"
在 manifest.json 文件中写一条注解,就可以把操作分组成下拉菜单。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
"actions": {
"MenuActions": {
"text": "{i18n>MenuButton}",
"menu": [
"DataFieldForAction::LROPODataService.changeCriticality",
"DataFieldForAction::LROPODataService.EntityContainer::unboundAction"
]
}
},
...
},
...
}
}
}
},
在列表报表的 control configuration 中,表格的 line item 注解下有一个 "actions" 属性,菜单按钮就加在这里(它不影响其它表格视图中可能用到的 line item 定义)。示例中的 "MenuActions" 只是这个菜单按钮的标识符;text 属性是菜单按钮实际显示的标签,"menu" 属性列出要包含的所有操作。"changeCriticality" 是绑定操作,可以直接通过服务访问;未绑定操作则需要通过 EntityContainer 访问,标识符里原来斜杠的位置要换成两个冒号。
动态的 CRUD 限制
搜索词:#DynamicCRUD
Edit、Create、Delete 三个操作的可见性可以动态调整。例如通过注解 @Capabilities.DeleteRestrictions,让删除操作取决于实体的某个字段。也可以直接给固定值。
从 UI5 1.100 起,值也可以是 Singleton。 Singleton 的写法比较特殊,如代码片段所示:路径值以 '/' 开头,随后是 singleton 的名字(在 Feature Showcase 里是 'Singleton'),最后是属性路径段。
annotate srv.RootEntities with @(
Capabilities.DeleteRestrictions : {
Deletable : deletePossible,
},
UI.UpdateHidden : updateHidden,
UI.CreateHidden: { $edmJson: { $Path: '/Singleton/createHidden' } },
);
上述注解位于 capabilities.cds 文件中。
@Capabilities.UpdateRestrictions 限制的是编辑模式下实体的可更新范围,比如所有字段变为只读,但 Edit 按钮并不会消失。这里应该改用 @UI.UpdateHidden 注解,它为 true 时会按预期把 Edit 按钮隐藏起来。
导航按钮
搜索词:#NavAction
把 UI.DataFieldForIntentBasedNavigation 作为 line item 加入,就能添加一个跳转到关联实体的导航操作。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$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,
},
...
],
);
上述注解位于 layouts_RootEntities.cds 文件中。
语义对象与操作在 manifest.json 文件中定义。其中的 application 属性包含如下代码片段:
"sap.app" : {
...,
"crossNavigation": {
"inbounds": {
"feature-showcase-worklist": {
"signature": {
"parameters": {},
"additionalParameters": "allowed"
},
"semanticObject": "FeatureShowcaseOrder",
"action": "manage",
"title": "Work List",
"subTitle": "Manage"
}
}
}
}
这里的 "FeatureShowcaseOrder" 就是要引用的语义对象,名字的第二部分是该应用的操作。例如可以有 "SalesOrder-manage"、"SalesOrder-view" 这类应用,语义对象与操作之间必须用短横线分隔。
RequiresContext 属性决定是否需要选中一条记录才能启用导航按钮。设为 true 时,可能还需要加上 Mapping 属性。该属性是一组本地属性与语义对象属性之间的映射数组:如果想用本地属性在语义对象所属的应用里做筛选,但两边属性名不一致,就需要它。示例中本地属性 'integerValue' 映射到语义对象属性 'integerProperty',因此选中 integerValue 等于 22 的实体后,导航会在语义对象应用中筛选 'integerProperty' 等于 22 的记录。
如果按钮是内联的,可以用图标代替文字作为按钮标签。显示图标时,criticality 会被忽略。
关键操作(Critical Actions)
搜索词:#CriticalAction
当操作用 @Common.IsActionCritical : true 标注后,调用该操作之前会先弹出气泡确认框,询问用户是否确定要执行选中的操作。
annotate srv.criticalAction with @(
Common.IsActionCritical : true
);
消息提示(Message Toast)
搜索词:#MessageToast
当后端发送 severity 等于 1 的消息时,界面上会显示消息提示(message toast)。severity 更高时,则显示对话框。 关于 CAP 后端如何发送消息,可见 SAP CAP 的 messaging 文档。
req.notify(`Critical action pressed`);
notify 是发送 severity 为 1 的消息的方法,req 是 CAP 收到的请求。
自定义操作(表格列表报表)
搜索词:"CustomActionLR"
借助扩展点(extension points),可以在列表报表的表格工具栏里添加自定义操作。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
"actions": {
...
"CustomActionLR" : {
"press": "sap.fe.showcase.lrop.ext.CustomActions.messageBox",
"enabled": "sap.fe.showcase.lrop.ext.CustomActions.enabledForSingleSelect",
"visible" : true,
"text": "{i18n>CustomActionLR}"
}
},
...
}
},
...
}
}
},
自定义操作本身另有说明:自定义操作(Custom Actions)。
设置表格类型
INFO: 我们建议使用 SAP Fiori tools(一套面向 SAP Business Application Studio 与 Visual Studio Code 的扩展),通过 Application Modeler 工具来配置应用。
搜索词(以下关键词均可在官方仓库中搜索到示例): "tableSettings"、"ResponsiveTable"、"GridTable"、"AnalyticalTable"
支持的表格类型有 ResponsiveTable、GridTable、AnalyticalTable 和 TreeTable。列表报表的表格类型可以在 manifest.json 文件中调整。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
...
"tableSettings": {
"type": "ResponsiveTable",
...
},
...
},
...
},
...
}
}
},
分析表格的示例位于 WorkList 应用的对象页上,定义在 WorkList 的 annotations.cds 文件 中。
树表格
搜索词(以下关键词均可在官方仓库中搜索到示例): #TreeTable、"TreeTable"
树表格可以显示层级数据,即父子层级结构。要在树表格中启用层级,需要在 manifest.json 中设置表格类型:
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"/OrganizationalUnits/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
"type": "TreeTable",
"hierarchyQualifier": "OrgUnitsHierarchy"
}
}
},
...
}
}
}
最关键的一点:manifest 中的 'hierarchyQualifier' 必须与 @Aggregation.RecursiveHierarchy 注解的 qualifier 一致,该注解用来定义父子层级。
annotate srv.OrganizationalUnits @Aggregation.RecursiveHierarchy #OrgUnitsHierarchy : {
ParentNavigationProperty : superOrdinateOrgUnit,
NodeProperty : ID,
};
ParentNavigationProperty 的值必须是指回同一实体的关联(association,例如 OrganizationalUnits),它决定节点的父节点;NodeProperty 则在层级中唯一标识一个节点,通常是该实体的 UUID 属性。
在 CAP 中还必须补上以下注解和属性,因为 SAP Fiori elements 需要它们,树表格才能正常工作:
[!NOTE] 计划将来由 CAP 自动补上这些内容,以减少配置开销。
extend srv.OrganizationalUnits with @(
// The columns expected by Fiori to be present in hierarchy entities
Hierarchy.RecursiveHierarchy #OrgUnitsHierarchy : {
LimitedDescendantCount : LimitedDescendantCount,
DistanceFromRoot : DistanceFromRoot,
DrillState : DrillState,
LimitedRank : LimitedRank
},
// Disallow filtering on these properties from Fiori UIs
Capabilities.FilterRestrictions.NonFilterableProperties: [
'LimitedDescendantCount',
'DistanceFromRoot',
'DrillState',
'LimitedRank'
],
// Disallow sorting on these properties from Fiori UIs
Capabilities.SortRestrictions.NonSortableProperties : [
'LimitedDescendantCount',
'DistanceFromRoot',
'DrillState',
'LimitedRank'
],
) columns { // Ensure we can query these fields from database
null as LimitedDescendantCount : Int16,
null as DistanceFromRoot : Int16,
null as DrillState : String,
null as LimitedRank : Int16,
};
树表格可以用于启用了草稿的实体,但存在一些限制,例如只显示活动实体,存在草稿时只显示草稿标识,而不显示草稿本身。
完整的限制清单见文档。
可以用 @Hierarchy.RecursiveHierarchyActions 指定一些附加操作:
ChangeSiblingForRootsSupported是一个布尔标记,控制根节点能否上移或下移,以及节点能否放在两个根节点之间。未定义时按 true 处理。ChangeNextSiblingAction指定一个绑定操作,用于在层级中上移或下移节点。当节点被拖放到另一个节点上以交换位置,或按下 Move Up / Move Down 按钮调整同层节点的顺序时,界面会调用该绑定操作,并传入 NextSibiling 参数。CopyAction指定用于复制绑定实体的绑定操作,复制之后可以在层级中粘贴。
annotate srv.OrganizationalUnits @(
...
Hierarchy.RecursiveHierarchyActions #OrgUnitsHierarchy : {
ChangeSiblingForRootsSupported,
ChangeNextSiblingAction : 'LROPODataService.moveOrgUnit',
CopyAction : 'LROPODataService.copyOrgUnit',
},
);
使用 Capabilities.UpdateRestrictions.NonUpdatableNavigationProperties 并给出父节点的关联,可以禁用层级上的所有变更操作。
[!CAUTION] 该限制目前在 API 层并未强制执行!
annotate srv.OrganizationalUnits @(
...
Capabilities.UpdateRestrictions.NonUpdatableNavigationProperties: [superOrdinateOrgUnit]
);
还可以通过 manifest.json 自定义新建按钮,为层级中不同种类的实体显示不同选项。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"/OrganizationalUnits/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
"type": "TreeTable",
"hierarchyQualifier": "OrgUnitsHierarchy",
"creationMode": {
"name": "CreationDialog",
"createInPlace": true,
"creationFields": "@com.sap.vocabularies.UI.v1.FieldGroup#creationDialog",
"nodeType": {
"propertyName": "category_code",
"values": {
"01": "Create a new department",
"02": {
"label": "Create a new division",
"creationFields": "name,description,isActive"
},
"03": "Create a new business unit"
}
},
"isCreateEnabled": ".extension.sap.fe.showcase.lrop.ext.controller.RootEntityLRExtension.isCreateEnabled"
},
...
}
}
},
...
}
}
}
示例使用的是 "CreationDialog" 创建模式,"NewPage" 和 "Inline" 同样可用("Inline" 只适用于对象页)。
提示:在树表格里使用 "nodeType" 属性,就可以实现这样的新建菜单 —— "values" 对象里每个键都对应一个单独的选项。
"values" 对象接受两种取值:字符串(直接作为标签使用),或对象(仅限 "CreationDialog"),对象里既包含标签,也包含一个替代的新建对话框,用来覆盖由 "creationMode" 中 "creationFields" 指定的原对话框。
使用扩展钩子 isCreateEnabled 可以控制新建按钮在什么上下文下可点击,它需要提供一个回调函数。该函数必须返回布尔值,决定在 "values" 对象中的某个值与树表格中选中节点的特定组合下是否允许新建。
在 Feature Showcase 里,这样就可以规定:根层级只能新建业务单元(business unit),业务单元下只能建分部(division),分部下只能建部门(department)。
[!CAUTION] 这只是启用/禁用新建按钮,要在 API 层强制约束,仍然需要后端的限制!
export default class RootEntityLRExtension extends ControllerExtension<ExtensionAPI> {
...
isCreateEnabled(value: String, parentContext?: Context) {
switch (parentContext?.getProperty("category_code")) {
case "03":
return value === "02"; // Only Divisions under Business Units
case "02":
return value === "01"; // Only Departments under Divisions
case "01":
return false; // Nothing under Departments
default:
return value === "03"; // Only Business Units at root level
}
}
...
}
还可以用更多扩展钩子来自定义树表格的行为。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"/OrganizationalUnits/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
"type": "TreeTable",
"hierarchyQualifier": "OrgUnitsHierarchy",
...
"isMoveToPositionAllowed": ".extension.sap.fe.showcase.lrop.ext.controller.RootEntityLRExtension.isMoveToPositionAllowed",
"isNodeMovable": ".extension.sap.fe.showcase.lrop.ext.controller.RootEntityLRExtension.isNodeMovable",
"isCopyToPositionAllowed": ".extension.sap.fe.showcase.lrop.ext.controller.RootEntityLRExtension.isCopyToPositionAllowed",
"isNodeCopyable": ".extension.sap.fe.showcase.lrop.ext.controller.RootEntityLRExtension.isNodeCopyable"
}
}
},
...
}
}
}
isNodeMovable 需要一个回调函数,它接收 OData 上下文,返回布尔值,决定节点能否通过拖放或上移/下移按钮在层级中移动。此外它还决定节点能否被剪切。
isMoveToPositionAllowed 同样需要一个回调函数,它是 isNodeMovable 的对应物:返回布尔值,决定节点能否移动到指定位置。为此 SAP Fiori elements 会传入两个 OData 上下文 —— 被移动的节点,以及该节点应移动到或放置到其下的目标节点。
isNodeCopyable 与 isCopyToPositionAllowed 的签名相同,区别是前者决定节点能否复制,后者决定复制出的节点能否粘贴到指定位置。
多视图
搜索词(以下关键词均可在官方仓库中搜索到示例): #multipleViews、"views"、[#multipleViews](https://github.com/SAP-samples/fiori-elements-feature-showcase/blob/main/../search?q=)、"quickVariantSelection"`
使用多视图,可以展示实体集的不同筛选条件和/或不同呈现方式,而无需手动设置筛选器。
单表格模式
在单表格模式下,所有视图都显示在同一个表格里,用表格标题旁的分段按钮切换视图。定义三个以上视图时,会改为显示下拉菜单。单表格模式的一个限制是:可以改变选中的实体集合(@UI.SelectionVariant),但不能改变实体的呈现方式(@UI.SelectionPresentationVariant),也不能改变实体集本身。
实现单表格模式,需要先定义选择变式(selection variant),然后在 manifest.json 文件中通过它的 qualifier(例如 #variant1)引用。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
...
"tableSettings": {
...
"quickVariantSelection": {
"paths": [
{
"annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant1"
},
{
"annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant2"
}
],
"hideTableTitle": false,
"showCounts": true
}
},
...
},
...
},
...
}
}
}
此外还可以指定每个视图是否显示自己的行数,以及是否对所有视图隐藏表格标题。"showCounts" 属性默认为 false,因为额外的 $count 请求会影响性能。
多表格模式
搜索词:"views"
在多表格模式下,表格上方会渲染一个图标标签栏(icon tab bar)用于切换视图。每个视图都有自己的表格、自己的表格工具栏以及(若已启用)变式管理,但只会显示当前选中标签的表格。这里可以使用 @UI.SelectionPresentationVariant 注解,也可以为某个标签指定另外的实体集。
单表格模式与多表格模式并不完全互斥。当多表格模式的某个视图用 SelectionVariant 作注解时,单表格模式下的各个视图还可以额外叠加使用;而当该视图使用 UI.SelectionPresentationVarian 时,就不能再叠加单表格模式的视图。
实现多表格模式,需要在 manifest.json 文件中通过 qualifier 引用 SelectionVariant 或 SelectionPresentationVariant。每个视图都必须有唯一的 "key" 属性作为标签标识。"annotationPath" 属性指向对应的 qualifier。这里同样可以选择显示各视图的记录数,但会影响性能。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"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
},
...
}
}
}
如果想让某个视图使用另一个实体集,只需在 manifest.json 的某个 path 条目里加上 "entitySet" 属性。引用的实体名要与 CAP 服务中的实体名一致,并且要把 SelectionVariant 或 SelectionPresentationVariant 注解到那个实体集上。显示其它实体集时,各视图的记录数会自动显示,showCounts 注解不再生效。主实体集上的筛选器在该属性也存在于另一实体集时会继续生效,否则被忽略。对于另一实体集独有的属性,无法添加筛选器。
更多信息见 SAP UI5 文档。
选择变式
搜索词:#SVariant
使用选择变式,可以定义实体集的字段应如何排序。"Text" 属性是视图标题,"SelectOptions" 属性包含全部排序参数。
annotate srv.RootEntities with @(
UI.SelectionVariant #variant1 : {
Text : '{i18n>SVariant1}',
SelectOptions : [
{
PropertyName : criticality_code,
Ranges : [
{
Sign : #I,
High : 2,
Option : #BT,
Low : 0,
},
],
},
],
},
...
);
"Option" 属性支持以下取值:等于(EQ)、介于(BT)、小于等于(LE)、大于等于(GE)、不等于(NE)、大于(GT)、小于(LT)。
上述注解位于 layouts_RootEntities.cds 文件中。
选择呈现变式
搜索词:#SPVariant
选择呈现变式可以同时定义实体的选择条件和呈现方式。PresentationVariant 目前支持 SortOrder 和 Visualizations 两个属性。这里的选择变式与呈现变式与单独使用的版本基本相同,只是这里的选择变式不包含 text 属性。
annotate srv.RootEntities with @(
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',
],
},
},
);
定义带 qualifier 的 UI.LineItem 集合后,就可以引用这个专用集合;使用该 UI.SelectionPresentationVariant 的视图会显示另外的列。
更多信息见 SAP UI5 文档。
新建对话框
搜索词:#CreationDialog
新建实体时,凡是标注了 @Core.Immutable 的字段都会弹出新建对话框要求填写,因为带这个注解的字段之后不能更新,值必须在创建时就给出。
annotate srv.RootEntities {
...
stringProperty @Core.Immutable;
...
};
定义默认排序
搜索词:#DefaultSort
使用 UI.PresentationVariant 注解可以定义默认排序。Visualizations 属性指定该排序应作用于哪些 line item。
annotate srv.RootEntities with @(
UI.PresentationVariant :{
SortOrder : [
{
Property : field,
Descending : false,
},
],
Visualizations : [
'@UI.LineItem',
],
},
);
未定义排序时,值按升序排列。实现位于文件 layout.cds 中。
在表格中启用多选
INFO: 我们建议使用 SAP Fiori tools(一套面向 SAP Business Application Studio 与 Visual Studio Code 的扩展),通过 Application Modeler 工具来配置应用。
搜索词:"selectionMode"
在表格设置中用属性 "selectionMode": "Multi" 可以在列表报表中启用多选。其它可选值有:Auto、Single、None。关于这些取值的更多说明见 SAP Fiori elements 文档。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
...
"tableSettings": {
"type": "ResponsiveTable",
"selectionMode": "Multi",
...
},
...
},
...
},
...
}
}
},
处理语义键字段
搜索词:#SemanticKey
使用 Common.SemanticKey 注解可以定义语义键字段,它由实体的一组字段组成的数组构成。指定的字段会以粗体显示,并在可能时显示编辑状态。目前这只对默认的 DataField 有效。
annotate srv.RootEntities with @(
Common.SemanticKey : [ field ],
);
上述注解位于 layouts_RootEntities.cds 文件中。
根据 criticality 高亮行项目
行项目可以根据其 criticality 用 @UI.Criticality 注解高亮。该注解必须是 @UI.LineItem 注解的一部分。
annotate srv.RootEntities with @(
UI.LineItem.@UI.Criticality : criticality_code,
);
给表格添加评分指示器
搜索词:#RatingIndicator
要给表格添加评分指示器(星级),需要给实体标注 @UI.DataPoint。该注解的 Value 属性决定显示多少颗星,x.25 到 x.74 之间的值显示为半颗星。Target 属性决定最多可以有几颗星。
annotate srv.RootEntities with @(
...
UI.DataPoint #ratingIndicator : {
Value : starsValue,
TargetValue : 4,
Visualization : #Rating,
Title : '{i18n>ratingIndicator}',
@Common.QuickInfo : 'Tooltip via Common.QuickInfo',
},
...
);
创建数据点后,还要把它加入 @UI.LineItem 注解:这里使用 UI.DataFieldForAnnotation 类型,target 指向该数据点。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Label : '{i18n>ratingIndicator}',
Target : '@UI.DataPoint#ratingIndicator',
@UI.Importance : #Low,
},
...
],
);
上述注解位于 layouts_RootEntities.cds 文件中。
给表格添加进度指示器
要给表格添加进度指示器,需要给实体标注 @UI.DataPoint。value 属性定义当前进度,target 属性定义最大进度。需要的话还可以给出 criticality。
annotate srv.RootEntities with @(
UI.DataPoint #progressIndicator : {
Value : integerValue,
TargetValue : 100,
Visualization : #Progress,
Title : '{i18n>progressIndicator}',
//Criticality: criticality,
},
...
);
创建数据点后,还要把它加入 @UI.LineItem 注解:这里使用 UI.DataFieldForAnnotation 类型,target 指向该数据点。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Label : '{i18n>progressIndicator}',
Target : '@UI.DataPoint#progressIndicator',
@UI.Importance : #Low,
},
...
],
);
上述注解位于 layouts_RootEntities.cds 文件中。
给表格添加带工具提示的字段
搜索词:#ToolTip
在列表报表中,可以通过一个变通做法让字段带上工具提示。 首先创建一个数据点,只包含 'Value' 属性和 '@Common.QuickInfo' 注解,后者定义显示的工具提示文本。
annotate srv.RootEntities with @(
...
UI.DataPoint #fieldWithTooltip : {
Value : dimensions,
@Common.QuickInfo : '{i18n>Tooltip}',
},
);
然后把这个数据点以 '@UI.DataFieldForAnnotation' 类型作为 line item 加入表格。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Target : '@UI.DataPoint#fieldWithTooltip',
Label : '{i18n>fieldWithToolTip}',
},
...
],
);
给表格添加智能微图
搜索词:#MicroChart
要给表格添加智能微图(smart micro chart),同样要先定义一个 @UI.DataPoint。以径向图(radial chart)为例,value 与 target value 属性是必填的,criticality 可选。
annotate srv.RootEntities with @(
...
UI.DataPoint #radialChart : {
Value : integerValue,
TargetValue : targetValue,
Criticality : criticality_code,
},
...
);
这个数据点需要在 @UI.Chart 注解的 measure attributes 中被引用。径向图的图表类型必须为 "#Donut",Measures 与 MeasureAttributes 是必填的。
annotate srv.RootEntities with @(
...
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 注解中某个 DataFieldForAnnotation 的 target,它就能显示在表格中。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Target : '@UI.Chart#radialChart',
Label : '{i18n>radialChart}',
},
...
],
);
示例中的注解位于 layouts_RootEntities.cds 文件中。
给表格添加联系人快速查看
搜索词:#Contact
要让某个数据字段显示联系人并提供联系人快速查看(contact quick view),需要先实现联系人快速查看。示例如下:
annotate srv.Contacts with @(
Communication.Contact : {
fn : name, //full name
kind : #org,
tel : [{
uri : phone,
type : #preferred
}],
adr : [{
building : building,
country : country.name,
street : street,
locality : city,
code : postCode,
type : #preferred
}],
}
);
Contact 还支持更多属性,列在 SAP Fiori elements 文档 中。
然后让这张联系人卡片作为某个 DataFieldForAnnotation 的 target,而该 DataFieldForAnnotation 本身是 @UI.LineItem 注解的一部分,这样就能在表格中显示。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Target : 'contact/@Communication.Contact',
Label : '{i18n>contactQuickView}'
},
...
],
);
联系人卡片通过实体的 contact 属性引用。 示例中的注解位于 layouts_RootEntities.cds 文件中。
给表格添加快速查看分面
搜索词:#QuickView
快速查看分面(quick view facet)是一个弹出层:点击列中的某个条目就能看到更多信息。它通常与「指向一」的关联配合使用 —— 列中显示关联名,点击后可以查看关联实体的更多信息。要启用快速查看分面,需要给关联实体标注 @UI.QuickViewFacet。它是一个 reference facet 数组,可以引用要在快速查看中显示的字段组(一组属性)。为了让快速查看的页眉更好看,关联实体通常还会标注 @UI.HeaderInfo。
annotate srv.Orders with @(
UI.FieldGroup #data : {
Label : '{i18n>Order}',
Data : [
{Value : field2},
{Value : integerProperty},
{Value : field4},
],
},
);
annotate srv.Orders with @(
UI.HeaderInfo :{
TypeName : '{i18n>Order}',
TypeNamePlural : '{i18n>Order.typeNamePlural}',
Title : {
$Type : 'UI.DataField',
Value : '{i18n>Order}',
},
Description : {
$Type : 'UI.DataField',
Value : field,
},
ImageUrl : '',
TypeImageUrl : 'sap-icon://blank-tag',
},
);
annotate srv.Orders with @(
UI.QuickViewFacets : [
{
$Type : 'UI.ReferenceFacet',
Target : '@UI.FieldGroup#data',
}
],
);
最后一步是把一个 UI.DataField 加入 @UI.LineItem 注解。该 data field 的值取键属性,快速查看分面就会自动可见。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataField',
Value : association2one_ID,
Label : '{i18n>Order}',
@UI.Importance : #High,
},
...
],
);
示例中的注解位于 layouts_RootEntities.cds 文件中。
此外还可以用 @Common.Text 和 @Common.TextArrangement,用名称属性替换 ID 值,让这一列更容易理解。
association2one @title : '{i18n>Order}' @Common.Text : association2one.field @Common.TextArrangement : #TextOnly;
注解位于 labels.cds 文件中。
指向实体所属应用的链接
搜索词(以下关键词均可在官方仓库中搜索到示例): FeatureShowcaseOrder、#Navigation
当实体标注了 @Common.SemanticObject 时,快速查看分面还会显示指向该实体相关应用的链接。
association2one @Common.SemanticObject : 'FeatureShowcaseOrder';
语义对象就是 manifest.json 中的应用名。其中的 application 属性包含如下代码片段:
"sap.app" : {
...,
"crossNavigation": {
"inbounds": {
"feature-showcase-worklist": {
"signature": {
"parameters": {
"ID": {
"required": false
},
"field3": {
"required": false
},
"integerProperty": {
"required": false
}
},
"additionalParameters": "ignored"
},
"semanticObject": "FeatureShowcaseOrder",
"action": "manage",
"title": "Work List",
"subTitle": "Manage"
}
}
}
}
这里的 "FeatureShowcaseOrder" 就是要引用的语义对象,名字的第二部分是该应用的操作。例如可以有 "SalesOrder-Manage"、"SalesOrder-View" 这类应用,语义对象与操作之间必须用短横线分隔。 html 文件中的应用描述就是快速查看分面里显示的应用名。在部署到 SAP WorkZone 的版本中,使用的是应用的 subtitle。
在响应式表格中把多个字段放进一列
搜索词:#MultiFieldsCol
如果把一个字段组用 UI.DataFieldForAnnotation 加入表格,就可以在一列里放多个字段。 首先要定义这个字段组。
annotate srv.RootEntities with @(
UI.FieldGroup #AdminData : {
Data : [
{Value : createdAt},
{Value : createdBy},
{Value : modifiedAt},
{Value : modifiedBy},
]
},
...
);
然后把一个 DataFieldForAnnotation 加入 @UI.LineItem 注解。
annotate srv.RootEntities with @(
UI.LineItem : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Target : '@UI.FieldGroup#AdminData',
Label : '{i18n>adminData}',
@UI.Importance : #High,
},
...
],
);
给表格添加图片
搜索词:#Image
图片通常是表格的第一列,能在视觉上引导用户。要给表格添加图片,只需把一个普通的数据字段加入 line item 即可。
annotate srv.RootEntities with @(
UI.LineItem : [
{
$Type : 'UI.DataField',
Value : imageUrl,
@UI.Importance : #High,
},
...
],
);
特殊之处只在于:存放图片 url 的属性必须标注 @UI.IsImageURL。示例的注解写在 labels.cds 文件中。
给表格添加货币或计量单位字段
搜索词:#Units
货币字段和计量单位字段的特殊之处在于,它们还有一个附带单位的字段。为了避免必须把两个属性都加进表格、又可能因为个性化设置导致其中一个不可见,可以给带值的属性标注单位。
计量单位用 @Measures.Unit 注解;货币用 @Measures.ISOCurrency 注解;百分比值用 @Measures.Unit : '%' 注解。
Feature Showcase 中的示例位于 labels.cds 文件中。
自定义货币或计量单位的小数位数
搜索词:#CustomUnitScale
默认情况下,标注了单位或货币的字段,其小数位数取自数据类型中定义的 scale。例如 Decimal(4,2) 有两位小数,Decimal(4,3) 有三位小数。
如果界面上要显示的小数位数与后端不同,可以通过调整计量单位或货币的值列表实体来自定义这一行为。
@CodeList.UnitsOfMeasure : {
Url : './$metadata',
CollectionPath : 'UnitOfMeasures',
}
service LROPODataService @(path : '/srv1') {
…
entity UnitOfMeasures as projection on persistence.UnitOfMeasures;
}
示例中通过指定 @CodeList.UnitsOfMeasure 注解来自定义单位。url 指向同一个服务的元数据,也可以指向其它服务的 url,此时 CollectionPath 指向那个服务中的实体。
然后需要给目标实体的键属性标注 @Common.UnitSpecificScale,指向存放该单位应显示多少位小数的属性。@Common.Text 与 @CodeList.ExternalCode 引用的字段会在选择单位时的值帮助中显示。
entity sap.common.UnitOfMeasures : CodeList {
// Search-Term: #CustomUnitScale
key code : String(30) @Common.Text : descr @Common.UnitSpecificScale : scale @CodeList.ExternalCode : name;
scale: Integer;
};
更多信息参见文档。
给表格添加链接
搜索词:#Link
用 UI.DataFieldWithUrl 可以给表格添加链接。'Value' 属性是可见文本,'Url' 是链接目标。
@UI.LineItem : [
{
$Type : 'UI.DataFieldWithUrl',
Url : fieldWithURL, //Target, when pressing the text
Value : fieldWithURLtext, //Visible text
Label : '{i18n>dataFieldWithURL}',
@UI.Importance : #Medium,
},
]
从 UI5 1.129.0 起,还可以给 'Value' 属性加注解,决定链接如何打开。
annotate srv.RootEntities with {
fieldWithURLtext @HTML5.LinkTarget : '_blank';
}
该注解的说明见此处。
让导航属性只在个性化设置中可选
搜索词(以下关键词均可在官方仓库中搜索到示例): #NavPropInAdaptability、DataField::association2one
关联(association)与组合(composition)加入 @UI.LineItem 注解后就可以作为表格的列。如果希望该属性只能通过个性化设置获得,则需要在 manifest.json 中额外配置。
@UI.LineItem : [
{
//Search-Term: #NavPropInAdaptability
Label : 'Navigation field only available via settings',
Value : association2one.country_code,
}
]
把 availability 属性设为 Adaptation,该属性只会出现在表格设置里,由用户按需添加。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
...
"columns": {
"DataField::association2one::country_code": {
"availability": "Adaptation"
}
}
},
...
},
...
}
}
}
列的 ID 遵循 DataField::<path> 的模式,导航路径中的点用两个 ':' 替换,例如 DataField::association2one::country_code。
添加自定义列(可扩展性)
搜索词:#CustomColumn
为了满足业务需求,可能需要给表格添加自定义列。借助 SAP Fiori elements 的扩展点可以做到。 首先要以 XML fragment 的形式创建这个附加列。该 fragment 应放在 webapp 的一个单独文件夹里。示例中的 fragment 包含一个 label,它由实体的 validFrom 和 validTo 属性拼成。
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m">
<Label text="{validFrom} - {validTo}"/>
</core:FragmentDefinition>
这个 label 要作为附加列显示,为此需要调整 manifest.json 文件。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.LineItem": {
...
"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"
}
}
}
},
...
},
...
}
}
}
line item 属性中的 columns 需要扩展出这个附加字段。key 属性必须唯一,template 指向该 XML fragment。该路径由两部分组成:第一部分是应用的命名空间(sap.fe.showcase.lrop),第二部分是在应用的 webapp 文件夹中定位 fragment 的路径(.ext.CustomColumn-DateRangeLR)。"availability" 属性定义该列是否可见,可选值为 "Default"、"Adaption" 或 "Hidden"。"properties" 属性定义在支持排序时可用哪些属性来排序,这些属性必须是实体自身的属性,不能是导航属性。
最后,"position" 定义该列应插入表格的什么位置。"position" 的可选值为 "Before" 或 "After","anchor" 必须是表格中已存在的数据字段,例如 "DataField::fieldWithCriticality"。
更多信息见 SAP UI5 文档。