一個詳盡的面向 SAP UI5 初學者的教程 - 如何在 SAP UI5 中繪製圖表 Chart
這是 Jerry 2021 年的第 65 篇文章，也是汪子熙公眾號總共第 342 篇原創文章。
觀滄海
曹操
東臨碣石，以觀滄海。
水何澹澹，山島竦峙。
樹木叢生，百草豐茂。
秋風蕭瑟，洪波湧起。
日月之行，若出其中;
星漢燦爛，若出其裡。
幸甚至哉，歌以詠志。
Jerry 之前的文章 在SAP UI中使用純JavaScript顯示產品主資料的3D模型檢視，介紹了在 SAP UI 上，利用 threejs(一個基於 WebGL，使用 JavaScript 進行 3D 模型變換和顯示的庫），顯示物料 3D 模型的方法。
目前第三方用於繪製圖表的 JavaScript 庫可謂玲琅滿目，其實 SAP UI5 自帶的 Viz 庫，足以勝任企業應用軟體裡大多數的畫圖需求。Jerry 試著在中文搜尋引擎里根據 SAP UI5 Viz 的關鍵字進行搜尋，發現關於該庫的中文資料非常少，因此就寫了這篇文章，介紹該庫的詳細使用步驟。
我們開啟 SAP UI5 的官方網站，找到使用 Viz 開發而成的圖表應用例子：
https://sapui5.hana.ondemand.com/#/entity/sap.viz.ui5.controls.VizFrame
從最簡單最容易入手的 Line Chart - 折線圖入手開始學習。
點選右上角的 download 按鈕之後，可以將這個例子的部分原始碼，下載到本地學習：
Jerry 2012 年剛剛開始學習 SAP UI5 時，也是從一行 HTML/JavaScript 程式碼都沒有編寫過的零基礎開始的，所以 SAP UI5 初學者，面對一大段陌生的原始碼時不知所措的心情，我也曾經也有。
在我看來，不少 SAP UI5 初學者在下載了這個折線圖的例子程式碼後，在使用它們開始學習時可能會遇到一些困擾，原因如下：
(1) 這段程式碼並不能夠直接在本地執行，因為缺少 Line Chart 顯示資料需要的 sample data. 這個資料檔案在 SAP 官網並未提供下載，只能由學習者線上訪問該例子應用後，手動從 Chrome 開發者工具的 network 標籤中下載。
(2) 如上圖高亮區域所示，這些設定介面用於動態調整 Line Chart 的顯示和渲染效果。從示例程式的完備性角度來說，這些功能非常有必要，但也大大增加了該例子的程式碼量。
(3) 原始碼裡的 package.json 和 ui5.yaml, 用於本地通過 @ui5/cli 這個命令列工具構建和本地執行 SAP UI5 應用，和 SAP UI5 Viz 本身的使用無關。
對於 SAP UI5 Viz 的初學者來說，可能當務之急是掌握一個圖表最基本的繪製方法。至於用 JavaScript 程式碼的方式，動態調整其顯示效果，應該是更高階的學習目標。
鑑於以上三點考慮，我對 SAP UI5 Viz 提供的折線圖例子的原始碼做了大幅地精簡和修改，其執行效果如下圖所示，程式碼量不到原來例子的 30%，相信初學者能憑藉該例子更快地上手：
從上圖能夠看出，Jerry 修改過後的例子，介面僅僅包含一張折線圖，移除了動態調整顯示效果的設定頁面。同時，補充了 SAP 標準例子程式裡缺失的 data.json 檔案，刪除了和 Viz 學習本身無關的 package.json 和 ui5.yaml 兩個檔案。
Jerry 例子的執行方法：
(1) 從 Jerry 的程式碼倉庫將程式碼下載到本地：
https://github.com/wangzixi-diablo/ui5-toolset
(2) 依次執行命令列 npm install, node local.js，然後瀏覽器訪問如下 url 即可：
下面詳細介紹 Jerry 例子的原始碼實現。
Line.view.xml
該檔案不到 40 行程式碼，展示瞭如何通過 VizFrame 標籤的方式，在視圖裡宣告 Viz 圖表。執行時，該 XML 檢視檔案被瀏覽器載入後，XMLTemplateProcessor 會被解析成一棵 DOM 樹，包括 VizFrame 在內的節點，會被例項化成對應的圖表例項。
下圖綠色區域是 XML 檢視的名稱空間(namespace)定義。比如第二行，定義了 sap.viz.ui5.controls 名稱空間，用字首 viz 標識。這樣，當我們在第 10 行宣告一個 Viz 圖表時，不需使用完整的命名格式 sap.viz.ui5.controls.VizFrame, 而直接用名稱空間的識別符號字首 viz, 後面緊跟著這個空間下的標籤 VizFrame 即可，這樣可以少敲幾個字元，也提高了 XML 檢視的可讀性。
第 11 行的 vizType 屬性指明瞭該圖表的型別為 line 即折線圖。
第 13 行的 FlattenedDataset，通過屬性 data，指明瞭折線圖的資料來源，欄位名為 milk.這個 milk 欄位可以在 sampledata 資料夾下的 data.json 檔案裡找到。milk 欄位的型別是一個數組，陣列每個元素的 Week 欄位，我打算用來作為折線圖裡 X 軸上的座標，而另外的 Revenue 和 Cost 欄位，我打算用來作為折線圖裡構成折線每個點的 Y 座標。
為了完成上述的設計，需要在 XML 視圖裡完成如下兩項設定：
(1) 將 data.json 裡陣列元素的 Week 屬性，通過大括號包裹的語法，賦給 DimensionDefinition 標籤，告訴 SAP UI5 Viz 框架，我想把我的業務資料裡的 Week 欄位，定義成折線圖裡的一個 Dimension(維度)。同理，將業務資料裡的 Revenue 和 Cost 欄位，定義成折線圖的兩個 Measure(度量)。
上圖綠色 uid 屬性，categoryAxis 和 valueAxis 分別代表 X 和 Y 軸的顯示專案，這是 SAP UI5 Viz 框架硬編碼的值，不能隨便指定為其他值。而 id 值為使用者指定，可以隨意指定。
(2) 通過 feeds 標籤，定義折線圖的 X 軸和 Y 軸需要顯示的資料。上圖定義了 X 軸座標，資料來自 data.json 檔案裡的 Week 欄位，而 Y 軸座標，來自 Revenue 和 Cost 欄位。
XML 檢視的程式碼，和其對應的執行時顯示效果，如下圖所示：
如果想在折線圖裡繪製第三條折線，需要的步驟是：
(1) 在 data.json 檔案裡新增新的業務資料欄位，比如 Income
(2) 在 XML 視圖裡定義一個新的 MeasureDefinition，繫結到前一步驟的 Income 欄位去
(3) 在 XML 視圖裡定義一個新的 FeedItem，型別為 Measure，名稱為前一步驟定義的 MeasureDefinition 的同名屬性。
點選折線圖上任意一個點，會彈出一個對話方塊，顯示該節點的 X 和 Y 座標：
這個彈出對話方塊的實現是通過 XML 視圖裡的 Popover 標籤完成的。
至此，XML 檢視的實現程式碼講解完畢。在 XML 檢視的頭部，定義了其對應的控制器的名稱，下面介紹其控制器的實現。
Line.controller.js
控制器的程式碼同樣經過 Jerry 大幅度精簡，剩下不到 50 行。主要做了三件事：
(1) 設定折線圖的數字顯示格式和折線圖節點的 Y 座標顯示(預設不顯示，所以需要用程式碼把 visible 設定為 true)。
SHORTFLOAT 和 SHORTFLOAT_MFD2 即緊湊顯示模式，能以 k 作為單位顯示較大的數字，比如 494000 顯示成 494k.
如果把上圖的格式控制和 title visible 屬性控制程式碼刪除，折線圖的外觀將變成如下圖所示：
對比之前的折線圖，不難發現，折線圖左邊的 Y 軸刻度值，現在不再以 k 作為單位；折線圖上每個節點的 Y 座標也不再顯示出來。
(2) 建立 JSONModel 例項，利用 setModel 方法繫結到折線圖例項上。
(3) 將 XML 視圖裡定義的 Popover 例項，繫結到折線圖例項上。
至此和 SAP UI5 Viz 使用相關的 XML 檢視和控制器的程式碼均介紹完畢。剩下的檔案都是每一個 SAP UI5 應用開發均需要使用到的 Common 檔案，這裡只簡要進行說明。
index.html
第 9 行從 SAP UI5 CDN 匯入庫檔案，以使用其最新版本。本文寫作時基於的 SAP UI5 版本為 1.94.0.
第 11 行 data-sap-ui-resourceroots 的屬性含義是，告訴 SAP UI5 載入器，如果遇到來自名稱空間 sap.viz.sample.Line 內的資原始檔，請從本地工程資料夾的根目錄下載入，而非從預設的 sapui5.hana.ondemand.com/resources 目錄去載入。
而下圖其他綠色高亮的 data-sap-ui-XX 等屬性，在 SAP UI5 官網有詳細的解釋，這裡不再贅述。
Component.js
該 Component 的名稱空間為 Jerry 自定義的 sap.viz.sample.Line，包含的元資料定義在工程內另一個檔案 manifest.json 內。我們可以把上圖 index.html 第 11 行的 data-sap-ui-resourceroots 屬性去掉做個實驗：
如此一來，SAP UI5 載入器就會試圖從預設的 sapui5.hana.ondemand.com/resources 去載入這個 Component.js, 當然會遇到 404 錯誤了：
manifest.json
該檔案定義了這個折線圖應用的元資料，包含應用的入口檢視，即被 SAP UI5 框架啟動後，載入的第一個 XML 檢視的名稱，以及該應用依賴的 SAP UI5 庫列表。
這個應用的全部原始碼介紹到此結束。相信有了本文的基礎，SAP UI5 的初學者，再回過頭去查閱 SAP UI5 官方網站上使用 Viz 庫繪製圖表的例子，理解起來會覺得容易得多。
感謝閱讀。
Jerry 的 SAP UI5 專題
更多Jerry的原創文章，盡在："汪子熙":