Fiori Elements 框架里 Smart Table 控件工作原理的深入解析

我们在Visual Studio Code 里通过 Guided Procedure，可以给 Fiori Elements 框架生成的 List Report 里的 Table，添加自定义按钮，如下图 Jerry 的按钮所示。

但实际工作中，有朋友反映，在 Fiori Elements 的 Guided Procedure 中通过向导，一路 Next Next，对于开发人员来说就是个黑盒子。虽然实现了需求，但不知道背后是怎么工作的，觉得一切很不踏实。

本文就来深入介绍 Fiori Elements 里 Smart Table 控件的工作原理。

我们知道 Fiori Elements List Report 的模板，包含了 SmartTable.fragment.xml 这个页面片段：

而该页面片段的源代码里，使用了 Smart Table 控件：

XML 视图的完整源代码：

<mvc:View 
	xmlns=".m"
	xmlns:mvc=".ui.core.mvc"
	controllerName=".ui.demo.smartControls.SmartTable"
	xmlns:smartTable=".ui.comp.smarttable">
	<smartTable:SmartTable 
		id="smartTable_ResponsiveTable"
		tableType="ResponsiveTable" 
		editable="false"
		entitySet="Products" 
		header="Jerry的产品" 
		showRowCount="true"
		useExportToExcel="false" 
		enableAutoBinding="true">
	</smartTable:SmartTable>
</mvc:View>

XML 视图里定义了一个 Smart Table 控件，第 10 行代码 entitySet=“Products”, 意思是让该控件，在运行时”智能地” 将名称为 Products 的 OData 模型里，所有符合某种条件的字段，渲染成表格列项目。

这个包含了 Smart Table 控件的 UI5 应用，最终渲染成包含如下三列的表格：产品 ID，价格 (含金额和货币单位) 以及产品名称。

我们打开 metadata.xml, 找到了 Product 模型包含的四个属性字段。这四个属性字段，都作为最后渲染出的列项目的备选字段。其中 Price 字段，通过属性 :unit, 和 CurrencyCode 字段关联起来，作为同一个表格备选列项目。

metadata.xml 的源代码：

<?xml version="1.0" encoding="utf-8"?>
<edmx:Edmx Version="1.0"
xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns:="http://www..com/Protocols/Data">
<edmx:DataServices m:DataServiceVersion="2.0">
<Schema Namespace="com..wt05" 
:schema-version="1" xmlns="http://schemas.microsoft.com/ado/2008/09/edm">
<EntityType Name="Product">
<Key>
<PropertyRef Name="ProductId" />
</Key>
<Property Name="ProductId" Type="Edm.String" :label="Jerry产品ID"
:filterable="false" />
<Property Name="Name" Type="Edm.String" MaxLength="30"
:label="Name" :filterable="false" />
<Property Name="Category" Type="Edm.String" :label="Category"
:filterable="true" />
<Property Name="Price" Type="Edm.String" :unit="CurrencyCode"
MaxLength="3" :label="Price" :filterable="false" />
<Property Name="CurrencyCode" Type="Edm.String" MaxLength="3"
:label="Currency" :semantics="currency-code" :filterable="true" />
</EntityType>
<EntityType Name="Currency">
<Key>
<PropertyRef Name="CURR" />
</Key>
<Property Name="CURR" Type="Edm.String" MaxLength="4"
:display-format="UpperCase" :text="DESCR" :label="Currency Code"
:filterable="false" />
<Property Name="DESCR" Type="Edm.String" MaxLength="25"
:label="Description" />
</EntityType>
<EntityType Name="Category">
<Key>
<PropertyRef Name="CAT" />
</Key>
<Property Name="CAT" Type="Edm.String" MaxLength="4"
:display-format="UpperCase" :text="DESCR" :label="Category"
:filterable="false" />
<Property Name="DESCR" Type="Edm.String" MaxLength="25"
:label="Description" />
</EntityType>
<EntityContainer m:IsDefaultEntityContainer="true"
:supported-formats="atom json">
<EntitySet Name="Products" EntityType="com..wt05.Product" />
<EntitySet Name="Currency" EntityType="com..wt05.Currency" />
<EntitySet Name="Category" EntityType="com..wt05.Category" />
</EntityContainer>
<Annotations Target="com..wt05.Product/CurrencyCode"
xmlns="http://docs.oasis-open.org/odata/ns/edm">
<Annotation Term="com..vocabularies.Common.v1.ValueList">
<Record>
<PropertyValue Property="Label" String="Currency" />
<PropertyValue Property="CollectionPath" String="Currency" />
<PropertyValue Property="SearchSupported" Bool="true" />
<PropertyValue Property="Parameters">
<Collection>
<Record Type="com..vocabularies.Common.v1.ValueListParameterOut">
<PropertyValue Property="LocalDataProperty"
PropertyPath="CurrencyCode" />
<PropertyValue Property="ValueListProperty"
String="CURR" />
</Record>
<Record
Type="com..vocabularies.Common.v1.ValueListParameterDisplayOnly">
<PropertyValue Property="ValueListProperty"
String="DESCR" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Annotation>
</Annotations>
<Annotations Target="com..wt05.Product/Category"
xmlns="http://docs.oasis-open.org/odata/ns/edm">
<Annotation Term="com..vocabularies.Common.v1.ValueList">
<Record>
<PropertyValue Property="Label" String="Category" />
<PropertyValue Property="CollectionPath" String="Category" />
<PropertyValue Property="SearchSupported" Bool="true" />
<PropertyValue Property="Parameters">
<Collection>
<Record Type="com..vocabularies.Common.v1.ValueListParameterOut">
<PropertyValue Property="LocalDataProperty"
PropertyPath="Category" />
<PropertyValue Property="ValueListProperty"
String="CAT" />
</Record>
<Record
Type="com..vocabularies.Common.v1.ValueListParameterDisplayOnly">
<PropertyValue Property="ValueListProperty"
String="DESCR" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Annotation>
</Annotations>
<Annotations Target="com..wt05.Product"
xmlns="http://docs.oasis-open.org/odata/ns/edm">
<Annotation Term="com..vocabularies.UI.v1.LineItem">
<Collection>
<Record Type="com..vocabularies.UI.v1.DataField">
<PropertyValue Property="Value" Path="Name" />
</Record>
<Record Type="com..vocabularies.UI.v1.DataField">
<PropertyValue Property="Value" Path="ProductId" />
</Record>
</Collection>
</Annotation>
</Annotations>
</Schema>
</edmx:DataServices>
</edmx:Edmx>						

尽管 Product 模型包含了 4 个字段作为表格备选列项目，但为什么最终渲染出的页面里，我们只看到了 3 个行项目？名为 Category 的字段为什么没能渲染成行项目？
答案在 metadata.xml 的注解区域。

帮助文档提到，其所属的 OData 模型被注解 com..vocabiularies.UI.LineItem 修饰，且类型为 com..vocabularies.UI.DataField 的字段，在运行时会被 UI5 框架绘制成表格列项目。

为了验证这个结论，我们对 metadata.xml 里的元数据进行一些修改。比如现在只定义两个表格列项目，分别为ProductId 和 Name. 同时，我用 :label, 给属性 ProductId 分配标签为 “Jerry产品ID”：

运行时的效果：Name 列表项出现在 ProductId 的左边，因为其在元数据里的定义，位置在 ProductId 之前。

至此我们已经了解了 Smart Table 表格列项目渲染的逻辑，最后来看看源代码实现。

我的 UI5 应用里，使用了 Smart Table 控件的 XML 视图，运行时被加载后，会被 UI5 的 XML 模板解析器， XMLTemplateProcessor 的方法 parseTemplate 所解析。XML 视图包含的 XML 字符串，会被反序列化成 DOM 并进行遍历。当模板解析器遍历 DOM 过程中，遇到 SmartTable 标签时，调用 SmartTable.init 方法，进行初始化操作：

根据本文前半部分的介绍，我们已经知道：如果缺乏 OData 元数据提供的注解，Smart Table 控件无法知道该怎么渲染表格的列项目。因此，SmartTable.js 也在 “OData 服务元数据成功取回” 这个事件上，注册了一个钩子函数 _onMetadataInitialised. 当 OData 服务的元数据取回之后，该回调函数被调用：

SmartTable.prototype._onMetadataInitialised = function() {
this._bMetaModelLoadAttached = false;
if (this.bIsInitialised) {
return;
}
this._bUseColumnLabelsAsTooltips = this.getUseColumnLabelsAsTooltips(); // keep value stable after initialization
// Check whether further custom columns where added in the meantime
this._updateInitialColumns();
this._fireBeforeInitialiseAndValidate();
this._validateCustomizeConfig(this.getCustomizeConfig());
this._createTableProvider();
if (!this._oTableProvider) {
return;
}
this._aTableViewMetadata = this._oTableProvider.getTableViewMetadata();
if (!this._aTableViewMetadata) {
return;
}
if (this._bUseColumnLabelsAsTooltips) {
this._oTable.getColumns().forEach(function(oColumn) {
var oHeader = null;
if (oColumn.getHeader) {
oHeader = oColumn.getHeader();
} else if (oColumn.getLabel) {
oHeader = oColumn.getLabel();
}
var oLabel = oHeader && oHeader.isA && (oHeader.isA(".m.Label") || oHeader.isA(".m.Text")) ? oHeader : null;
var oTooltipTarget = this._isMobileTable ? oLabel : oColumn;
var oTooltip = oTooltipTarget ? oTooltipTarget.getTooltip() : null;
if (oTooltipTarget && oLabel && !oTooltip && !oTooltipTarget.isBound("tooltip")) {
if (oLabel.isBound("text")) {
var oBindingInfo = _getClonedBindingInfo(oLabel.getBindingInfo("text"));
oTooltipTarget.bindProperty("tooltip", oBindingInfo);
} else {
oTooltipTarget.setTooltip(oLabel.getText());
}
}
}, this);
}
// Set width for custom columns after metadata is initialized
if (this.getEnableAutoColumnWidth()) {
this._oTable.getColumns().forEach(this._setWidthForCustomColumn, this);
}
if (!this._isMobileTable && this.getDemandPopin()) {
this.setDemandPopin(false);
Log.error("use SmartTable property 'demandPopin' only  with responsive table, property has been set to false");
}
this.detachModelContextChange(this._initialiseMetadata, this);
// Indicates the control is initialised and can be used in the initialise event/otherwise!
this.bIsInitialised = true;
delete this._bInitialising;
this._updateP13nDialogSettings(true);
this._bTableSupportsExcelExport = this._oTableProvider.getSupportsExcelExport();
this._bMultiUnitBehaviorEnabled = this._oTableProvider.getMultiUnitBehaviorEnabled();
this._listenToSmartFilter();
this._createVariantManagementControl(); // creates VariantMngmntCtrl if useVariantManagement OR useTablePersonalisation is true.
// Control is only added to toolbar if useVariantManagement is set otherwise it acts as
// hidden persistance helper
this._createToolbarContent();
this._applyToolbarContentOrder();
this._aAlwaysSelect = this._oTableProvider.getRequestAtLeastFields();
this._createContent();
this._createPersonalizationController();
// Create a local JSONModel to handle editable switch
this._oEditModel = new JSONModel({
editable: this.getEditable()
});
// Set the local model on the SmartTable
this.setModel(this._oEditModel, "sm4rtM0d3l");
this.attachEvent("_change", this._onPropertyChange, this);
this.fireInitialise();
// Trigger initial binding if no Variant exists -or- if it is already initialised
if (!this._oVariantManagement || (this._oVariantManagement && this._bVariantInitialised)) {
this._checkAndTriggerBinding();
}
};

该函数是 UI5 中 SmartTable 控件的一个方法，主要负责在元数据初始化完成后设置表格的一些核心功能和行为。此方法是内部方法，通常在控件初始化过程中自动调用。

该函数每个步骤都旨在确保 SmartTable 控件能够根据提供的配置和元数据正确初始化，提供灵活的个性化设置，并为最终用户呈现丰富、互动的数据表格视图。通过这种方式， UI5 框架提供了强大的工具，支持开发人员创建高度定制的应用程序视图，满足复杂的业务需求。

在该回调函数执行的上下文里，因为 OData 服务元数据已经处于可访问状态，所以 Smart Table 有足够的信息，能够开始渲染逻辑的执行：

下图第 97 行的高亮代码，getLineItemAnnotation, 即是 Smart Table 控件，准备从 Product 这个 EntityType 里，解析出符合表格列项目渲染要求的字段列表：

注意下图第 1909 行硬编码的字符串 com..vocabularies.UI.v1.LineItem, 这就是 UI5 框架代码里查找 Smart Table 待渲染列表项字段的依据。最后解析出的两个列表项字段，Name 和 ProductId，就存储在函数返回变量 oResolvedAnnotation.

有了这个信息，Smart Table 就知道该渲染哪些字段作为表格列项目了。

至此，本文已经完成了 Smart Table 控件渲染表格列项目的原理介绍，以及相应的 UI5 框架是如何解析待渲染列项目的源代码实现的介绍。

希望本文能给对 Smart Table 技术内幕感兴趣的朋友们有所启发。

原文链接：https://juejin.cn/post/7332390317559627826 作者：JerryWang_sap