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,遵循其许可证。

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 属性数组中。

操作参数的值帮助

搜索词:#ValueHelpParameter

实体的属性常常配有值帮助,让新建实体更容易、错误输入更少。操作参数同样可以配置值帮助。

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 注解。该注解必须与参数写在一起(内联)。

操作参数的默认值

搜索词:#ParameterDefaultValue

用注解 @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"`

使用多视图,可以展示实体集的不同筛选条件和/或不同呈现方式,而无需手动设置筛选器。

单表格模式

搜索词:"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 高亮行项目

搜索词:#LineItemHighlight

行项目可以根据其 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 文件中。

给表格添加进度指示器

搜索词:#ProgressIndicator

要给表格添加进度指示器,需要给实体标注 @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 文档。


Object Page