Fiori elements 特性全集演示 · 列表报表 · 标题区域

项目

内容

官方仓库

SAP-samples/fiori-elements-feature-showcase

业务场景

用一套可运行的应用演示 Fiori elements 的每一种表格、表单与页面特性

技术栈

SAP Fiori elements for OData V4、SAPUI5、注解(annotation)、灵活编程模型

对应课程

UX405、UX406、UX410、UX400

对应路径

第 3 条 开发 SAPUI5 应用

为什么值得做:Fiori elements 的能力边界靠文档很难建立直觉。 这个仓库把特性做成可点开的界面,点一下就知道某个注解会产生什么效果。

动手要点:

  • 把应用跑起来,逐个对照 annotations.cds —— 改一个注解,刷新看变化。

  • 这个「改注解看效果」的循环,是掌握 Fiori elements 最快的路径。

本页内容抓取自官方仓库 SAP-samples/fiori-elements-feature-showcase,共收录 1 篇官方文档(README 与 docs)。原仓库内容版权归 SAP SE,遵循其许可证。

列表报表 · 标题区域

启用变式管理(Variant Management)

搜索词:"variantManagement"

变式管理(保存筛选设置与表格个性化设置)默认是启用的。不过,通过注解 "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 文档。

大小写不敏感的筛选

搜索词:#CaseInsensitiveFiltering

使用注解 @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 文档。

自定义操作(全局列表报表)

搜索词:"CustomActionLRGlobal"

借助扩展点,可以在列表报表的标题区域添加自定义操作。

"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」一节。