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,遵循其许可证。
列表报表 · 标题区域
启用变式管理(Variant Management)
变式管理(保存筛选设置与表格个性化设置)默认是启用的。不过,通过注解 "variantManagement": "None" 可以在 manifest.json 中将它禁用。
"RootEntityListReport": {
...
"options": {
"settings": {
"entitySet": "RootEntities",
"variantManagement": "None",
...
}
}
}
禁用变式管理后,该位置改为显示应用标题。借助 manifest.json 文件中的 subTitle 注解,可以把它改成自定义名称。appSubTitle 属性对应的名称必须放在应用 webapp 文件夹内的 i18n.properties 文件中。
"sap.app": {
...
"subTitle": "{{appSubTitle}}",
...
}
启用实时模式(Live Mode)
搜索词:"liveMode"
为简化用户体验,可以在应用中启用实时模式:它会去掉筛选栏上的 GO 按钮,直接应用筛选条件与搜索查询。
它在 manifest.json 中启用:
"RootEntityListReport": {
...
"options": {
"settings": {
"liveMode": true,
...
}
}
}
定义筛选器
搜索词(以下关键词均可在官方仓库中搜索到示例): #FilterDefault、#HideFilter、#FilterGrouping、#VisibleFilters、#ValueHelps、#DependentFilter
默认值
搜索词:#FilterDefault
使用注解 @Common.FilterDefaultValue 可以定义默认值,示例见 field-control.cds。该注解不允许复杂值,而且在切换变式时该注解不再被考虑。对于复杂值,更好的方案是 [@UI.SelectionPresentationVariant],它在“默认排序与筛选”一节中说明。
更多信息见 SAP UI5 文档。
隐藏筛选字段
搜索词:#HideFilter
为减少列表报表中可用筛选器的数量,可以用 @UI.HiddenFilter 注解标注属性来隐藏它们。示例见 field-control.cds 文件。
annotate srv.RootEntities {
...
fieldWithURLtext @UI.HiddenFilter;
...
};
筛选器分面(Filter Facets)
搜索词:#FilterGrouping
另一个不错的特性是 @UI.FilterFacets,它可以把实体的可用属性组织成若干分组,让筛选器适配更容易。
annotate srv.RootEntities with @(
UI.FilterFacets : [
{
Target : '@UI.FieldGroup#chartData',
Label : '{i18n>chartData}',
},
{
Target : '@UI.FieldGroup#location',
Label : '{i18n>location}',
},
],
);
annotate srv.RootEntities with @(
UI.FieldGroup #chartData : {
Data : [
{Value : integerValue},
{Value : targetValue},
{Value : forecastValue},
{Value : dimensions},
{Value : integerValue},
]
},
);
实现代码在 layout.cds 文件中。
选择字段
搜索词:#VisibleFilters
@UI.SelectionFields 是一个注解,用于指定一个字段数组:这些字段默认作为筛选器显示在列表报表的筛选栏中,用户因此不需要自己去适配筛选器。该注解用在 layout.cds 文件中。
annotate srv.RootEntities with @(
UI.SelectionFields : [
field,
fieldWithPrice,
criticality_code,
],
);
更多信息见 UI5 文档。
必填筛选字段
搜索词:#RequiredFilter
使用注解 @Capabilities.FilterRestrictions.RequiredProperties 可以定义一组必填筛选字段。在特性演示中,为演示目的只把属性 'stringProperty' 设为必填。该注解可以在 capabilities.cds 文件中找到。
annotate srv.RootEntities with @(
...
Capabilities.FilterRestrictions : {
...
RequiredProperties : [
stringProperty
],
},
);
为 Date 类型的筛选字段启用语义日期
自 UI5 版本:1.99.0
搜索词(以下关键词均可在官方仓库中搜索到示例): #SemanticDateFilter、useSemanticDateRange
对于 Date 类型的筛选字段,可以通过注解 @Capabilities.FilterRestrictions.FilterExpressionRestrictions 启用语义日期。该注解需要一个数组,每个对象对应一个字段。"Property" 值必须是该日期字段的名称,"AllowedExpressions" 值是 'SingleValue' 或 'SingleRange'。
SingleValue 目前提供选择某个日期,或选择 Today、Yesterday、Tomorrow 的选项。
SingleRange 则额外增加 From/To、From、To 和 Year To Date 选项。
annotate srv.RootEntities with @(
Capabilities.FilterRestrictions : {
FilterExpressionRestrictions : [
{
Property : 'validFrom',
AllowedExpressions : 'SingleRange'
}
],
...
},
);
如果希望完全禁用语义日期,可以在 manifest.json 文件中把 useSemanticDateRange 属性设为 false,默认值为 true。此外,还可以在 manifest 中为语义日期范围指定默认值。下面的文档链接列出了所有选项,请注意这些选项必须全部使用大写。
"RootEntityListReport": {
"options": {
"settings": {
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.SelectionFields": {
"useSemanticDateRange": true,
"filterFields": {
"validFrom": {
"settings": {
"defaultValues": [{"operator": "LASTYEARS", "values": [10]}]
}
}
}
}
},
}
}
},
更多信息见 SAP UI5 文档。
大小写不敏感的筛选
使用注解 @Capabilities.FilterFunctions 并在数组中包含字符串 'tolower',即可启用大小写不敏感的筛选。
它只能应用于整个服务,启用后对筛选栏筛选、表格个性化中的筛选以及值帮助内部的筛选都有效。
annotate LROPODataService with @(
Capabilities.FilterFunctions : [
'tolower'
],
);
如果该注解不存在,则大小写敏感筛选生效,由后端决定默认行为。 示例在 capabilities.cds 文件中。
更多信息见 SAP UI5 文档。
值帮助(Value Help)
搜索词: #ValueHelps,#RadioButtons
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',
}
]
}
});
};
Label 属性显示为值帮助对话框的标题,CollectionPath 属性指向服务中为该值帮助提供取值的实体集。如果值帮助较为复杂、属性名不匹配,或者你想配置值帮助中显示哪些字段,可以为 Parameters 属性提供参数。
值帮助显示为下拉框
当值帮助中的可选值集合较小时,用下拉框代替对话框来选择值可能更好。这可以通过 @Common.ValueListWithFixedValues 注解实现。
值帮助显示为单选按钮
如果再给该属性加上 @Common.ValueListWithFixedValues.@Common.ValueListShowValuesImmediately 注解,值帮助就不会渲染为下拉框,而是渲染为单选按钮。
annotate schema.RootEntities with{
criticality_code @(Common : {
ValueListWithFixedValues,
ValueListWithFixedValues.@Common.ValueListShowValuesImmediately,
});
};
默认情况下渲染为纵向,通过 manifest.json 中的一项设置可以调整为横向。
"RootEntityListReport": {
"options": {
"settings": {
"controlConfiguration": {
"@com.sap.vocabularies.UI.v1.FieldGroup#ShowWhenInEdit": {
"fields": {
"DataField::criticality_code": {
"formatOptions": {
"radioButtonsHorizontalLayout": false
}
}
}
}
}
}
}
}
目前只有页面上的字段支持渲染为单选按钮,操作对话框中的字段尚不支持。
所有值帮助注解都在 value-helps.cds 文件中。
依赖筛选(值帮助)
搜索词:#DependentFilter, #ConstantFilter
依赖筛选可以通过值帮助的输入参数实现。国家与地区就是一个例子:地区的值帮助应当只显示所选国家下的地区,而国家是实体的另一个属性。
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,
},
//To only show the connected values
{
$Type : 'Common.ValueListParameterFilterOnly',
ValueListProperty : 'country_code',
},
{
$Type : 'Common.ValueListParameterIn', //Input parameter used for filtering
LocalDataProperty : country_code,
ValueListProperty : 'country_code',
},
]
}
});
};
这里 region 属性(它是指向代码列表的关联)被加上了 ValueList 注解。为实现筛选,通过 Common.ValueListParameterIn 参数把头部实体中的 "country_code" 属性映射到 region 的 "country_code" 属性上。实现代码见 value-helps.cds。
如果希望对某个值做静态筛选,可以使用 Common.ValueListParameterConstant,此时需要提供要筛选的属性以及用于筛选的常量值。
annotate schema.RootEntities with {
regionWithConstantValueHelp @(Common : {
Text : regionWithConstantValueHelp.name,
TextArrangement : #TextFirst,
ValueListWithFixedValues: true,
ValueList : {
Label : '{i18n>region}',
CollectionPath : 'Regions',
Parameters : [
{
$Type : 'Common.ValueListParameterInOut',
ValueListProperty : 'code',
LocalDataProperty : region_code
},
{
$Type : 'Common.ValueListParameterConstant',
ValueListProperty : 'country_code',
Constant : 'DE',
},
]
}
});
}
依赖筛选(多输入值帮助)
搜索词:#MultiValueWithDependentFilter
依赖筛选也可以使用父实体的属性,这对带值帮助的多输入字段尤其有用。在示例中,根实体分配了一个国家,并且要为根实体分配多个地区,为此使用了分配实体。若只想显示所选国家的地区,可以使用对根实体的引用。
annotate schema.AssignedRegions 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.ValueListParameterIn',
LocalDataProperty : root.country_code,
ValueListProperty : 'country_code',
},
]
}
});
}
代码片段中的 'LocalDataProperty' 指向国家引用,并把它映射到 'Regions' 实体的 'country_code' 属性上,'Regions' 正是该值帮助的目标实体。
值帮助本身标注在分配实体中的该属性上,这个属性同时也是 DataField 的 value 路径所指向的目标属性。
annotate srv.RootEntities with @(
...
UI.FieldGroup #location : {
Data : [
...
{
Value : regions.region_code,
Label : '{i18n>MultiInputFieldWithVH}'
}
]
},
...
)
添加导航属性
搜索词(以下关键词均可在官方仓库中搜索到示例): navigationProperties、#NavigationProperties
导航属性也可以添加到筛选栏中。为此需要把导航路径加入 @UI.SelectionFields 注解。
annotate srv.RootEntities with @(
UI.SelectionFields : [
...
childEntities1.criticalityValue_code
],
);
如果希望把导航属性作为筛选器分面添加到 Adapt Filters(适配筛选器)对话框中,就必须在 manifest.json 文件中引用它们。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
...
"@com.sap.vocabularies.UI.v1.SelectionFields": {
"navigationProperties": [ "childEntities1", "Order/decimalProperty" ],
...
}
},
...
}
}
},
只引用关联本身时,该关联的所有字段都会出现在为这个关联单独提供的筛选器分面中;如果定义指向该关联某个具体属性的路径,则只会把该属性添加到 Adapt Filters 对话框中。
关于导航属性作为筛选字段的更多信息见 SAP Fiori elements 文档。
自定义筛选器
搜索词:customFilter
当数据值采用特殊格式时(例如评级),自定义筛选器就很有用。它的实现包含多个部分。 首先,在 manifest.json 中为列表报表补充下面几行。 在 "controlConfiguration" 下扩展选择字段("@com.sap.vocabularies.UI.v1.SelectionFields")。 "property" 属性是实体集中被筛选的属性;"template" 属性指向作为筛选器的 XML 片段。 也可以使用带 "placement" 和 "anchor" 的 "position" 属性;不指定时,自定义筛选器放在末尾。 自定义筛选器的名称必须与属性名一致,否则会报错。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"controlConfiguration": {
...
"@com.sap.vocabularies.UI.v1.SelectionFields": {
"filterFields": {
"starsValue": {
"label": "{i18n>customFilter}",
"property": "starsValue",
"template": "sap.fe.showcase.lrop.ext.CustomFilter-Rating"
}
}
}
},
...
}
}
},
推荐做法是直接用 value="{path: 'filterValues>', type: 'sap.fe.macros.filter.type.Value'}" 绑定筛选值,并使用一种筛选值类型(例如 Value 或 Range)。
此外,还可以通过格式选项,用其他运算符代替默认的 'EQ'。
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m" xmlns:l="sap.ui.layout">
<!-- Search-Term: "customFilter" -->
<HBox alignItems="Center" core:require="{handler: 'sap/fe/showcase/lrop/ext/CustomFilter-Rating'}" width="100%" >
<!-- Example for adapting the used operator, using GT (greater than) instead of default EQ -->
<RatingIndicator
id="MyCustomRatingIndicatorId" 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>
下面的代码是重置函数的一个示例。"starsValue" 是实体集中被筛选的属性名。
...
export default class RootEntityLRExtension extends ControllerExtension<ExtensionAPI> {
...
onResetRating(oEvent: Button$PressEvent) {
this.base.getExtensionAPI().setFilterValues("starsValue");
}
}
关于自定义筛选器的更多信息见 SAP Fiori elements 文档。
自定义操作(全局列表报表)
借助扩展点,可以在列表报表的标题区域添加自定义操作。
"RootEntityListReport": {
...
"options": {
"settings": {
...
"content" : {
"header" : {
"actions" : {
"CustomActionLRGlobal" : {
"press": "sap.fe.showcase.lrop.ext.CustomActions.messageBox",
"enabled": "sap.fe.showcase.lrop.ext.CustomActions.enabled",
"visible" : true,
"text": "{i18n>CustomActionLRGlobal}"
}
}
}
}
}
}
},
自定义操作本身的说明见「Custom Actions」一节。