- SAP Managed Tags:
前言
为了满足客户对于 SAP 分析云的统计图样式的多样化需求，我学习了故事中的微件加载项，并根据代码仓库中的一版初始示例，开发了一版功能更为丰富的中文示例包。在学习和开发过程中，我主要参考了官方提供的微件加载项开发者指南文档。下面我将结合文档和这版中文示例包的具体代码，系统地介绍一下微件加载项，并分享我关于开发的经验与心得。
介绍
SAP 分析云提供了自定义微件和微件加载项两个功能，来丰富故事中系统提供的原生统计图的样式。自定义微件提供了极大自由度，使得用户可以使用其他外部库的统计图来展示数据。而对于只需要在原生统计图的基础上改变部分样式，并且最大程度利用原生统计图的数据绑定等功能的需求，微件加载项是最佳选择。目前，微件加载项一共有三个类型，分别是：
- 工具提示：支持的统计图类型不包括数值点图
- 绘图区（常规）：支持的统计图类型包括条形图/柱形图、堆积条形图/柱形图、堆积面积图和折线图
- 绘图区（数值点）：支持的统计图类型为数值点图
工具提示类型的加载项专门修改统计图上工具提示的样式，绘图区类型的加载项专门修改统计图上绘图区部分的样式。
微件加载项的源文件由一个 JSON 文件和多个 JavaScript 文件组成。JSON 文件用于声明加载项的元信息，JavaScript 文件中使用 Web Component 的语法实现微件加载项的功能。每个 JSON 文件至多可以声明三个类型的微件加载项各一个，这样会使得它们的名字相同但类型不同。每个类型的微件加载项必须要有一个实现功能的主 JavaScript 文件，可选一个在故事内修改加载项表现的设置面板 JavaScript 文件。
以示例包中的 index.json 文件为例："extensionPoint"为"sap.addOn.viz.plotarea.general"说明该微件加载项是绘图区（常规）类型的，之后"webcomponents"部分有两项，"kind"为"main"的说明该 JavaScript 文件是实现功能的主源文件，"kind"为"builder"的说明该 JavaScript 文件是设置面板源文件。其他部分也挑选几个简单介绍一下，"id"需要唯一，"name"是这个 JSON 文件声明的微件加载项在系统中的名称。
原理
微件加载项的原理大致如下，在 JSON 文件中设置隐藏原来的统计图的组成部分，通过 setExtensionData 函数拿到原生统计图的信息，在此基础上做修改后渲染出新的统计图并将其覆盖到原来统计图的位置上。以示例包中的 index.json 文件为例：在每个微件加载项的"properties"部分，有预设好的这样一些以"sapHide"为开头的属性，对它们的"default"属性设置为 true 会隐藏原生统计图中对应的部分，设置为 false 则会保留原生统计图中对应的部分。在示例包中，对于绘图区（常规）类型的加载项，保留了原生的 X 轴标签，其他部分都重新渲染，因此"sapHideOriginalXAxisLabels"是 false 而其他都是 true。
接下来我们来看一下 setExtensionData 函数能拿到原生统计图的哪些信息。这一函数在 viz-plotarea.js 文件中的第560行，由于添加了第561行代码，因此我们可以在浏览器中查看拿到的原生统计图的信息。
我们在 SAP 分析云上先上传一下示例包。打开故事面板，选择微件加载项，点击添加按钮。
在上传文件面板，依次选择 JSON 文件为示例包中的 index.json 文件，资源文件为示例包中的 Archive.zip 文件，这个 zip 文件实际上就是由示例包中的4个 JavaScript 文件打包而成的。点击继续，这样微件加载项就上传完成了。
接下来我们新建一个优化体验故事，插入一个条形图，选择一个示例模型，设置一下账户和维。
在自定义加载项部分点击添加加载项，选择类型为绘图区（常规），选择我们刚刚上传的加载项。
最后打开浏览器的开发者工具，在 Console（控制台）面板，我们可以看到打印出来一个 Object，右键复制后，在代码编辑器中粘贴，我们就可以得到原生统计图的信息。
我们可以拿到原生统计图的类型和大小，坐标轴位置长宽，以及图上每个系列的每个数据点、数据标签、坐标轴标签的位置、长宽、颜色、内容等信息，这些就是我们能拿到的所有有关原生统计图的信息，微件加载项就是在这些信息的基础上重新渲染统计图的。
代码
这一部分我将结合示例包和具体代码，介绍一下绘图区（常规）类型的加载项的各功能是如何实现的。绘图区（数值点）类型的加载项功能较少也较为简单，就不赘述了。
圆角柱形
首先是“圆角柱形”，这一项可以在设置面板选择是否开启，开启后会使得原本柱形图的长方形一段变成圆角的。
这一部分在绘图区（常规）类型的加载项的主源文件viz-plotarea.js中的renderData函数中实现，这一函数负责数据图形的渲染。
其主要步骤是，根据原来的统计图类型和柱形宽度计算出圆角的度数，以 css 字符串形式保存，再根据设置选项"this._rounded"（布尔类型）的值来决定是否使用这一 css 字符串，最后使用 setAttribute 函数将它添加到元素属性中。
"this._rounded"的值由设置面板控制，要实现这一功能需要在三个文件中添加相关代码。首先是设置面板源文件 viz-plotarea-builder-panel.js，在其中写好该选项勾选框的 html 代码。
为其添加监听器，当勾选框状态改变时，触发事件，将更新好的值传递给系统。
同时也要添加 set 和 get 函数用于获取和修改控制面板该项的状态。
然后是 index.json 文件，需要在其中的"properties"属性声明这一项，这样系统才能识别，并且可以在"default"属性设置一个默认值。
最后是主源文件 viz-plotarea.js，需要添加 set 函数，set 函数会根据系统传递的值修改本文件内的"this._rounded"，随后调用 render 函数渲染整个统计图，从而实现加载项的功能。
这一套通过设置面板控制加载项部分功能的开关的逻辑，对于加载项的每个功能都是类似的，之后将不再赘述。
柱形尺寸
接下来我们看一下“柱形尺寸”。这一项可以修改统计图上柱形的宽度，从而也影响了柱形之间的间隔。
这一部分同样在主源文件 viz-plotarea.js 中的 renderData 函数中实现。通过设置面板传递过来的"_dataMarkerSize"计算出 increment，再根据柱形的方向和 increment 修改柱形的宽度 width 和坐标 x 或 y。
最后再设置到元素的 style 属性中。
图片填充
接下来我们看一下“图片填充”。这一项可以在设置面板选择图片，用图片堆叠填充柱形。步骤如下：勾选图片填充后，会出现文件选择器，点击选择一张图片即可。
这一部分我是通过将图片文件转换为 base64 编码字符串，从而保存在 index.json 中的。转换过程在设置面板源文件 viz-plotarea-builder-panel.js 中实现，利用了浏览器提供的 FileReader 类。
同时需要注意，在 index.json 中声明时，类型需要相应地设置为"String"。
最后在主源文件 viz-plotarea.js 中的 renderData 函数中，使用 css 的语法将图片的 base64 编码设置到元素样式的"background-image"属性中，实现图片的堆叠填充。注意，这里通过修改 css 的语法，还可以修改图片堆叠的方向，或者实现图片的拉伸填充，本文就不详细阐述了。
环形图数据标签
接下来我们来看一下“环形图数据标签”，这一项目前只对柱形图生效。在设置面板开启后，统计图上数据标签会变成一个显示其占总体百分比的环形图，还可以在设置面板调整它的大小。
这一部分是在主源文件 viz-plotarea.js 中的 renderLabel 函数中实现的。在此之前首先需要利用 reduce 函数计算出每个系列的总值。
接下来绘制一个 svg 环形图，过程较为繁杂，是 viz-plotarea.js 文件的325到433行，就不详细解释了。过程中利用"this._donutDataLabelSize"，就可以实现对 svg 图形大小的设置。
自定义单位
接下来我们看一下“自定义单位”。这一项可以在设置面板配置，使得统计图上的数据标签以配置的单位展示。
这一部分同样是在主源文件 viz-plotarea.js 中的 renderLabel 函数中实现的。实现方法较为简单，就是把标签的原始数值，除以“单位进制”，最后再加上“单位名”，以 html 的形式内嵌在元素中。
交错数据标签
最后我们来一起看一下“交错数据标签”。这一项只对折线图有效，因此需要更换一下统计图类型，同时更换了一个成员更多的维，更好地展现效果。开启这一项后，折线图的数据标签将会一上一下交替，目的是为了防止标签的重叠。
这一部分同样是在主源文件 viz-plotarea.js 中的 renderLabel 函数中实现的。实现方法也很简单，就是间隔地把数据标签的纵向位置加上一些，使得原本默认都是在数据点上方的数据标签，间隔一个移动到数据点下方。
心得分享
经过对官方文档的学习和实际开发，我认为微件加载项的功能是很强大的，原因在于可以覆盖原来的统计图，重新渲染。这一点提供了充分的自由度，因为可以随意添加任何浏览器支持的内容，例如上面提到的图片填充和 svg 图形。但是微件加载项的功能也存在一大限制，在于能获得的关于原生统计图的信息是很有限的。对于开发者想要实现的效果，最终是依赖于这些原生信息的，这意味着可能需要添加一些额外的复杂逻辑才能实现效果。我认为加载项最简单的应用，是改变原生统计图的一些字体样式颜色，或是为标签添加一些自定义的图标。这些功能没有作为示例包的正式功能，但在源文件的代码中有所体现。据我了解，用户对于数据标签的需求较多，读者可以考虑如何使用微件加载项更好地解决折线图或柱形图的标签防遮挡问题和标签的自定义样式问题。也可以尝试开发使得统计图样式更加酷炫的加载项，参考下图。
结语
感谢各位能看到这里，我学习微件加载项的时间也不长，文中若有对加载项理解不到位的地方还请多多包涵，也可以在评论区交流见解。本次中文示例包的功能还很不完善，旨在为各位开发者提供一个思路，希望各位开发者能有所收获，开发出满足需求、功能强大的微件加载项。
此示例包仅用于学习交流，不可做生产用途使用。在使用前请检查并彻底阅读其中可能使用的第三方库的许可至关重要。使用本资源包中的示例即表示您确认您已了解并同意遵守这些许可中规定的所有条款和条件。请负责任地使用此资源库，使用该资源包所带来的任何风险将自行承担。
1 Comment
