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 Object Page
搜索词:#OPContentArea
内容区域的内容通过 @UI.Facet 注解添加,该注解是一个由 @UI.ReferenceFacet 与 @UI.CollectionFacet 组成的数组。reference facet 是单个表单、图表或表格,collection facet 是一组 reference facet 的集合。collection facet 中的各个 reference facet 按水平方向排列,并会自动换行。@UI.Facet 注解中的 facet 会显示为不同的页签(Tab),或在同一页面上显示为上下相邻的不同主题。二者的切换在 manifest.json 文件中完成,可选值为 "Tabs" 或 "Page"。当一个小节里只有一种类型的内容、且该小节的标题与内容标题相同时,小节标题不会显示。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"sectionLayout": "Tabs",
...
}
}
},
要注意的是,collection facet 必须带有 ID,否则界面无法正常工作。第 3 层及更深的 collection facet 不予考虑;如果用到表格,建议采用 Tab 表现形式。
更多信息见 SAP Fiori elements 文档。
内容区域对象页的通用特性
搜索词(以下关键词均可在官方仓库中搜索到示例): #DisplayTextAndID、#HidingContent、#Preview、#SideContent
为值帮助输入字段显示文本与 ID
与直接显示难以阅读的长 ID 相比,可以把 ID 换成实体中的另一个属性值,例如名称属性。
@Common.Text 注解指定应当用哪个值取代原值显示,@Common.TextArrangement 注解定义新文本的显示方式,可选值为 '#TextOnly'、'#TextFirst'、'#TextLast'、'#TextSeperate'。
annotate schema.RootEntities with {
...
criticality @Common.Text : criticality.name @Common.TextArrangement : #TextFirst;
...
};
该特性并不局限于替换 ID,任何属性都可以加上这个注解。
隐藏内容
搜索词:#HidingContent
任何标题区 facet、分区或数据字段都可以通过 @UI.Hidden 注解隐藏。该注解只支持布尔值,不能使用表达式绑定,例如 '!'。
annotate srv.RootEntities with @(
UI.Facets : [
...
{
$Type : 'UI.ReferenceFacet',
Target : '@UI.FieldGroup#ShowWhenInEdit',
Label : '{i18n>ShowWhenInEdit}',
@UI.Hidden: IsActiveEntity,
},
...
],
);
预览
搜索词:#Preview
若 collection facet 中的某个 reference facet 带有 @UI.PartOfPreview 注解且其值为 false,则应用加载后该 reference facet 不会显示。此时该子分区收在界面上的 Show more 按钮之下。
annotate srv.RootEntities with @(
UI.Facets : [
...
{
$Type : 'UI.CollectionFacet',
...
Facets : [
...
{
$Type : 'UI.ReferenceFacet',
Target : '@UI.FieldGroup#advancedChartData',
ID : 'advancedChartData',
Label : '{i18n>advancedChartData}',
@UI.PartOfPreview : false
},
],
},
...
],
);
侧边内容
搜索词(以下关键词均可在官方仓库中搜索到示例): #SideContent、"sideContent"
对象页上的分区和子分区可以带有可切换的侧边内容,默认不显示。
这类侧边内容由一个 XML 片段定义,切换由一个自定义操作完成,该操作调用 this.showSideContent("\[side-content-key\]"); 函数。
这个函数不必通过自定义操作来调用。
侧边内容本身在 manifest.json 文件中引用。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"content": {
...
"body": {
...
"sections": {
"customSectionQualifier": {
...
"sideContent": {
"template": "sap.fe.showcase.lrop.ext.SideContent",
"equalSplit":true
}
},
...
"childEntities1Section" : {
"sideContent": {
"template": "sap.fe.showcase.lrop.ext.SideContent"
}
}
}
},
...
}
}
}
},
"template" 属性引用 XML 片段。当 "equalSplit" 设为 true 时,侧边内容与原有内容按 1:1 分割屏幕;当 "equalSplit" 为 false 或未定义时,屏幕按 2:1 分割,比例偏向原有内容。
限定符(qualifier)是侧边内容应出现的那个 facet 的 ID。该用哪个限定符取决于 facet 的结构,请查阅文档,找出符合目标要求的限定符。
切换函数可能如下所示。也可以传入第二个布尔参数,此时不再切换,而是直接设置可见性。
...
export default class RootEntityOPExtension extends ControllerExtension<ExtensionAPI> {
...
toggleSideContent(oBindingContext: ODataContextBinding) {
this.base.getExtensionAPI().showSideContent("customSectionQualifier");
}
toggleSideContentItem1(oContextInfo: ODataContextBinding) {
this.base.getExtensionAPI().showSideContent("childEntities1Section");
}
}
自定义操作的实现在其他章节中说明。
表单
搜索词:#Form
表单是一组字段。用 @UI.FieldGroup 注解把这些字段编为一组,再把该字段组加入 @UI.Facets 注解,才会显示出来。
字段组的数据放在 "Data" 属性中。普通数据字段不需要 "$Type" 属性,给出 "Value" 属性就够了。
annotate srv.RootEntities with @(
...
UI.FieldGroup #ShowWhenInEdit : {
Data : [
{Value : field},
{Value : fieldWithCriticality},
{Value : fieldWithUoM},
{Value : fieldWithPrice},
{Value : criticality_code},
{Value : contact_ID},
{Value : association2one_ID},
]
},
...
);
字段组本身也有 "Label" 属性,但界面上只会使用 reference facet 的 "Label" 属性。
各字段的界面标签在 labels.cds 文件中通过 @title 属性定义。这是在 CAP 中定义界面标签的推荐做法,也可以使用数据字段的 "Label" 属性。
UI.Facets : [
...
{
$Type : 'UI.ReferenceFacet',
Target : '@UI.FieldGroup#ShowWhenInEdit',
Label : '{i18n>ShowWhenInEdit}',
...
},
...
]
关联字段
搜索词:#ConnectedFields
当两个字段在语义上相互关联时,可以把它们并排显示在同一个标签下,以体现数据关系。
关联字段用 @UI.ConnectedFields 注解定义。"Template" 属性是一个字符串,定义字段的显示顺序以及两个字段之间显示什么,例如一个斜杠。这里的字段引用用的是 Data 属性的限定符,而不是实体属性的实际名称。'Data' 属性包含这两个字段。要注意的是,字段对象的 "$Type" 属性必须设为 "UI.DataField",否则关联字段不会显示出来。
UI.ConnectedFields #ConnectedDates :{
Label : '{i18n>ConnectedField}',
Template : '{integerValue} / {targetValue}',
Data : {
integerValue : {
$Type : 'UI.DataField',
Value : integerValue,
},
targetValue : {
$Type : 'UI.DataField',
Value : targetValue,
},
},
},
随后,把关联字段作为「用于注解的数据字段」的 Target 来引用,即可在表单中显示。
annotate srv.RootEntities with @(
...
UI.FieldGroup #Section : {
Data : [
...
{
$Type : 'UI.DataFieldForAnnotation',
Target : '@UI.ConnectedFields#ConnectedDates',
},
...
]
},
...
);
目前它们还无法在表格或标题区 facet 中渲染。
自定义内容
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"CustomContentFieldGroup"
SAP Fiori elements 允许向表单添加自定义数据字段。新增的字段以 XML 片段的形式创建,并在 manifest.json 文件中引用。 在 "controlConfiguration" 属性下,要用字段组的限定符(例如 #ShowWhenInEdit)引用相应字段组。为自定义字段定义一个 ID,示例中为 "DateRange"。"template" 属性是 XML 片段的命名空间加名称,"position" 属性定义字段插入的位置。"placement" 的合法取值为 "After" 与 "Before",锚点(anchor)是字段组中另一个数据字段。两个冒号之后是数据字段的值属性名,此处为 "association2one_ID"。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
...
"@com.sap.vocabularies.UI.v1.FieldGroup#timeAndDate": {
"fields": {
"CustomContentFieldGroup": {
"label": "{i18n>validityPeriodOP}",
"template": "sap.fe.showcase.lrop.ext.CustomField-DatePicker",
"position": {
"placement": "Before",
"anchor": "DataField::validTo"
}
}
}
},
...
},
...
}
}
},
更多信息见 SAP Fiori elements 文档。
表单操作与导航
表单可以有自己的操作,默认显示在分区的右上角。添加操作与导航,只需把对应的数据字段("DataFieldForAction" 或 "DataFieldForIntentBasedNavigation")加入该表单字段组的 "Data" 数组即可。如果希望操作属于表单工具栏而不是分区工具栏,该数据字段需要额外设置 "Inline : true"。
annotate srv.RootEntities with @(
...
UI.FieldGroup #Section : {
Data : [
...
{
$Type : 'UI.DataFieldForIntentBasedNavigation',
Label : '{i18n>IntentBasedNavigation}',
SemanticObject : 'FeatureShowcaseOrder',
Action : 'manage',
RequiresContext : true,
IconUrl : 'sap-icon://cart',
Mapping : [
{
$Type : 'Common.SemanticObjectMappingType',
LocalProperty : integerValue,
SemanticObjectProperty : 'integerProperty',
},
],
@UI.Importance : #High,
},
{
$Type : 'UI.DataFieldForAction',
Action : 'LROPODataService.EntityContainer/unboundAction',
Label : '{i18n>formActionEmphasized}',
@UI.Emphasized : true,
},
{
$Type : 'UI.DataFieldForAction',
Action : 'LROPODataService.changeProgress',
Label : '{i18n>formAction}',
Inline : true,
},
]
},
...
);
自定义操作(对象页分区表单)
自定义操作也可以加到对象页上表单所在的分区。分区的限定符就是注解中给出的 ID。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
...
"content": {
...
"body": {
...
"sections": {
"customSectionQualifier": {
...
"actions" : {
"CustomActionSectionForm" : {
"press": "sap.fe.showcase.lrop.ext.CustomActions.messageBox",
"enabled": "{= ${ui>/editMode} !== 'Editable'}",
"visible" : true,
"text": "{i18n>CustomActionSection}"
},
...
}
},
...
}
},
...
}
}
}
},
自定义操作本身的说明见「自定义操作」一节。
如果希望操作属于表单工具栏而不是分区工具栏,就要为字段组定义该操作,并把 "inline" 属性设为 true。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
...
"@com.sap.vocabularies.UI.v1.FieldGroup#Section": {
...
"actions" : {
"CustomActionForm" : {
"press": "sap.fe.showcase.lrop.ext.CustomActions.messageBox",
"enabled": true,
"visible" : true,
"inline" : true,
"text": "{i18n>CustomActionOPFooter}"
}
}
},
...
},
...
}
}
},
表格
搜索词:"Control"、"personalization"、"enableFullScreen"、#OPTableTitle、"quickVariantSelection"、"creationMode"、"enableExport"
表格分区最常用于子实体或其他关联实体。其实现分为两部分。
首先,关联实体或子实体需要 @UI.LineItem 注解,由它定义显示哪些字段。
annotate srv.ChildEntities3 with @(
UI.LineItem :[
{
Value : field,
},
],
);
其次,需要让 @UI.LineItem 注解成为一个 reference facet。
annotate srv.RootEntities with @(
UI.Facets : [
...
{
$Type : 'UI.ReferenceFacet',
Target : 'childEntities3/@UI.LineItem',
Label : '{i18n>childEntities3}',
},
...
],
);
在对象页启用变式管理(Variant Management)
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"Control"
要为对象页上的表格启用变式管理,需要在 manifest.json 文件中把 "variantManagement" 属性设为 "Control"。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"variantManagement": "Control",
...
}
}
}
启用个性化(Personalization)
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"personalization"
此外,还可以分别打开或关闭列的个性化调整、表格排序以及用户筛选表格这几项能力。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"childEntities1/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
...
"personalization": {
"column": true,
"sort": false,
"filter": true
},
...
},
...
},
...
},
...
}
}
}
该注解位于 manifest.json 文件中。
启用全屏模式(Full Screen Mode)
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"enableFullScreen"
在 manifest.json 文件中加上注解 "enableFullScreen": true,表格右上角就会多出一个按钮,用于以全屏模式查看表格。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"childEntities1/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
...
"enableFullScreen": true,
...
},
...
},
...
},
...
}
}
},
为对象页表格添加标题
搜索词:#OPTableTitle
对象页表格的标题取自 @UI.HeaderInfo 注解的 "TypeNamePlural" 属性。
annotate service.ChildEntities1 with @(
UI.HeaderInfo :{
...
TypeNamePlural : '{i18n>childEntities1.typeNamePlural}',
...
},
);
如果分区标题与表格标题相同,或者没有提供 @UI.HeaderInfo 注解,表格标题就不会显示。另外,如果表格是某个子分区中唯一的内容且带有标题,那么子分区的标题也不会显示。
为表格工具栏添加分段按钮
表格工具栏中的分段按钮用于在不同视图之间切换。如果为表格指定了 3 个以上的视图,分段按钮会被下拉按钮取代。视图变式在 manifest.json 文件中指定,位于 line item 的 "tableSettings" 属性下,line item 即表格的数据源。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"childEntities1/@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"
},
{
"annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant3"
},
{
"annotationPath": "com.sap.vocabularies.UI.v1.SelectionVariant#variant4"
}
],
"hideTableTitle": false,
"showCounts": true
},
...
},
...
},
...
},
...
}
}
},
关于多视图的更多信息见「列表报表」部分。
在对象页上启用表格条目的行内创建
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"creationMode"
行内创建模式可在 manifest.json 文件中启用。 在表格设置下,创建模式的名称必须是 "Inline",另一个可选值是 "NewPage"。 通过 "createAtEnd" 属性可以定义 "Inline" 模式下的新行是建在表格末尾,还是建在表格开头(第一行)。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"childEntities1/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
...
"creationMode": {
"name": "Inline",
"createAtEnd": true
},
...
},
...
},
...
},
...
}
}
},
使用「导出到电子表格」功能
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"enableExport"
对象页上的「导出到电子表格」功能会随复制/粘贴功能一起启用,否则默认禁用。可以在 manifest.json 文件中按需为各个表格启用。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"childEntities1/@com.sap.vocabularies.UI.v1.LineItem": {
"tableSettings": {
...
"enableExport": true
},
...
},
...
},
...
}
}
},
有关该功能及其限制的更多信息见 SAP Fiori elements 文档。
自定义操作(对象页分区表格)
搜索词:"CustomActionOPTableToolbar"
自定义操作也可以加到对象页某个分区的表格工具栏中。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
"childEntities1/@com.sap.vocabularies.UI.v1.LineItem": {
...
"actions" : {
"CustomActionOPTableToolbar" : {
"press": "sap.fe.showcase.lrop.ext.CustomActions.messageBox",
"enabled": "{= %{deletePossible} === true}",
"visible" : true,
"text": "{i18n>CustomActionOPTableToolbar (enabled when delete enabled)}"
}
}
},
...
},
...
}
}
},
自定义操作本身的说明见「自定义操作」一节。
图表
搜索词:#ChartSection
除了标题区中的微型图表(micro chart),图表也可以作为分区使用,不过实现起来更复杂。
首先,作为图表数据源的实体需要用 @Aggregation.ApplySupported 注解做好准备。
annotate srv.ChartDataEntities with @(
Aggregation.ApplySupported : {
GroupableProperties : [
dimensions,
criticality_code
],
AggregatableProperties : [
{
Property : integerValue,
},
],
}
);
其次,实体需要 @Analytics.AggregatedProperties 注解,它定义支持哪些聚合方法。这些方法应与可聚合属性上定义的支持方法一致。
annotate service.ChartDataEntities with @(
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'
}
],
);
之后就可以定义 @UI.Chart。请注意,"Measures" 属性写的是聚合方法的名称;如果只写实体属性(例如 "integerValue"),图表就不会显示。
"Dimensions" 属性给出默认维度;第二个图表维度属性是可下钻到的类别。
加到 "Actions" 属性中的操作会显示在图表工具栏中。
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}',
},
]
},
...
);
最后,需要把 @UI.Chart 注解作为 reference facet 加入 @UI.Facets 注解。
annotate srv.RootEntities with @(
UI.Facets : [
...
{
$Type : 'UI.ReferenceFacet',
Target : 'chartEntities/@UI.Chart',
Label : '{i18n>chart}'
},
...
],
);
要为维度做语义着色,需要给维度属性加上 `@UI.ValueCriticality` 注解,把该属性的各个可能值与一个严重度(criticality)对应起来。
annotate srv.ChartDataEntities with {
criticality @(
UI.ValueCriticality : [
{
Value : 0,
Criticality : #Neutral
},
{
Value : 1,
Criticality : #Negative
},
{
Value : 2,
Criticality : #Critical
},
{
Value : 3,
Criticality : #Positive
}
]
);
};
关于图表分区的更多信息见 [SAP Fiori elements 文档](https://sapui5.hana.ondemand.com/#/topic/653ed0f4f0d743dbb33ace4f68886c4e)。
自定义分区与子分区
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"customSectionQualifier"
自定义分区与子分区也可以通过以下方式实现:在 manifest.json 文件的 "content" 属性下的 "body" 属性中,把所需的 XML 片段作为一个分区加进去。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"content": {
...
"body": {
...
"sections": {
"customSectionQualifier": {
"template": "sap.fe.showcase.lrop.ext.CustomSection",
"position": {
"anchor": "Section",
"placement": "After"
},
"title": "{i18n>CustomSection}",
...
},
...
}
},
...
}
}
}
},
自定义分区的 ID 必须唯一。"template" 属性是 XML 片段的路径,"position" 属性定义该分区放在哪里:其 "anchor" 是另一个分区的 ID,placement 可以是 "Before" 或 "After"。
自定义子分区
INFO: 建议使用 SAP Fiori tools——它是 SAP Business Application Studio 与 Visual Studio Code 的一组扩展——通过 Application Modeler 工具来配置应用。
搜索词:"customSubSectionQualifier"
自定义子分区的实现方式与自定义分区类似。分区的限定符是 collection facet 的 ID。子分区位于 "subSections" 属性中,"template" 是 XML 片段的路径。该字符串由 manifest 中的 ID("sap.fe.showcase.lrop")与片段在 webapp 文件夹中的路径拼成("ext" 是文件夹,"CustomSubSection" 是片段名称)。"visible" 属性同样接受绑定表达式,例如 "enabled="{= ${ui>/editMode} === 'Editable'}"。未提供 "position" 属性时,片段放在末尾。
"RootEntityObjectReport": {
...
"options": {
"settings": {
...
"content": {
...
"body": {
...
"sections": {
...
"collectionFacetSection": {
"subSections": {
"customSubSectionQualifier": {
"template": "sap.fe.showcase.lrop.ext.CustomSubSection",
"title": "{i18n>customSubSection}",
"visible": true
}
}
},
...
}
},
...
}
}
}
},