自訂展示 > ThingWorx 應用程式小工具 > Dygraph 小工具
Dygraph 小工具
Dygraph 小工具適於顯示任何時間序列圖表。在 ThingWorx Apps 中，小工具用於許多地方：
• 在「趨勢與疑難排解」中，用於趨勢詳細資訊頁的圖表上 (PTC.Factory.TrendTroubleshooting.TrendDetail)
• 在 Controls Advisor 中，用於「用戶端數量」與「標籤數量趨勢」圖表 (PTC.Factory.KEPServerEX.DetailPage) 上
• 在「生產 KPI」中，用於「生產歷史記錄資料」頁面 (PTC.Factory.ProductionHistoricalData、PTC.Factory.C_ProductionHistoricalData_[ReleaseVersion]) 的「狀態歷史記錄」與「KPI 趨勢」圖表上
• 在「Asset Advisor」中，對於「效能」頁面的「本週狀態」圖表 (PTC.SCA.SCO.AssetMonitor.AssetDetail.PerformanceMonitorContainerMashup)
這些實作可作為範例參考。
Dygraph 小工具透過 Dygraphs 圖表資料庫實行功能子集，並已自訂以用於 ThingWorx Apps。雖然 Dygraphs 文件 ( http://dygraphs.com/) 是有用資源，但 Dygraph 小工具僅支援使用本主題中記錄的功能。
用於 Dygraph 小工具的公用程式服務
PTC.SCA.SCO.DygraphUtils 物件包含以正確格式為小工具的 JSONData 內容產生資料的服務。GenerateDygraphData 服務將透過物件的值串流或資料庫，以 Dygraph 小器具能夠顯示的格式，為一系列指定屬性提供歷史記錄資料。若有一組有效的輸入，此服務會以 CSV 格式傳回可以繫結到小工具的 JSONData 內容的資料。您可以建立使用 GenerateDygraphData 服務的新服務，以為個別混搭中的小器具產生特定資料。
此外，PTC.SCA.SCO.DygraphUtils 項目還包含 PTC.Factory.ProductionHistoricalData 與 PTC.Factory.C_ProductionHistoricalData_[ReleaseVersion] 混搭中之小工具所使用的服務。
• GenerateKPIPropertiesHistoryForDygraph - 為「生產 KPI」的特定設備擷取「生產歷史資料」頁面「KPI 趨勢」圖表中針對所選時間範圍顯示的 KPI 屬性歷史記錄資訊。此服務是使用 GenerateDygraphData 服務直接從資料庫擷取特定屬性之歷史記錄資料的範例。
• GenerateStatusHistoryForDygraph - 針對「生產 KPI」中的設備，擷取顯示在「生產歷史資料」頁面的「狀態歷史記錄」圖表中的狀態歷史記錄資訊。亦會擷取顯示在「Asset Advisor」之「效能」頁面上的資訊。此服務會擷取所選時間範圍的狀態變更資訊，以及所選時間範圍之前的資料點。透過這一點，可顯示適用於整個所選時間範圍的狀態資訊，而不只是所選時間範圍內發生的狀態變更。
相關 Dygraph 小工具屬性
此類屬性可在「設定」下方，小工具的「屬性」標籤中找到︰
內容
描述
annotationsDivName
將顯示註釋資訊的 HTML div 元素。此為顯示在小工具之外的元素。欲將 div 置於混搭中的任何位置，請建立 HTML 元素，並將 div 置於該元素內。在使用者按一下「KPI 趨勢」圖表中的變更事件方塊時，隨即顯示註釋範例。
ConnectSeparatedPoints
選取此核取方塊後，圖表上的任何資料間隙均會相連。
CustomBars
選取此核取方塊後，每個 CSV 儲存格均剖析為 "low;middle;high"。於低、高點之間的每個點繪製錯誤柱狀圖，而系列自身則穿過中線。這主要用於當圖表顯示平均值時顯示其範圍。且就算只顯示較少的點，仍可呈現任一點是高於或低於預期的值。
dateFormat、useDateFormat
可讓您設定 X 軸日期的格式。使用下列來自於 Moment.js Javascript 函式庫的函式：moment(date).format(XXX)
DisplayTagName
選取此核取方塊後，標籤或內容的完整名稱會隨同其值一起顯示在圖表圖例中。對於較長的標籤或屬性名稱，這可能會導致出現資料截斷。選取此核取方塊後，會顯示與標籤或屬性名稱之方形顏色相同的破折號，而非名稱。標籤或屬性名稱的有色方形會顯示在圖表右側的資訊面板中。
DrawAxisX、DrawAxisY、DrawAxisY2
選取此核取方塊後，圖表上會顯示該軸的水平軸線 (包含值)。
DrawGridX、DrawGridY、DrawGridY2
選取此核取方塊後，圖表上會顯示該軸的垂直軸線 (包含值)。
DrawPoints
選取此核取方塊後，所有點均會永久顯示在圖表中，而不是僅僅於滑鼠暫留時顯示。
DygraphSynchDefault
選取此核取方塊後，當載入混搭時，將呼叫 Dygraphs 圖表資料庫的同步處理應用功能，同步頁面上的所有圖表。必須為混搭中的所有圖表選取此核取方塊才能使該功能正常工作。依預設，不會選取此核取方塊。
FillArea
選取此核取方塊後，線條所定義的區域以顏色填充。此屬性不相容於自訂的列。
HideY-AxisValues
選取此核取方塊後，Y 軸的數字會隱藏，但仍會顯示軸線。
LegendPosition
確定圖表上圖例的方位。預設值為 On Mouse Over。
showDecimal
選取此核取方塊後，小數數值的標籤會顯示於 Y 軸上。
StackedGraph
選取此核取方塊後，圖形線條呈堆疊狀。
Stepped
選取此核取方塊後，圖表線在不同點之間呈階梯狀，而非一條直線。
useAnnotation
選取此核取方塊可使用 annotationsJSON 或 annotationsDivName。
UsePercentageFormat
選取此核取方塊後，Y 軸值會顯示為百分比。僅適用於左側的 Y 軸。
此類屬性可在「繫結」下方，小工具的「屬性」標籤中找到︰
內容
描述
annotationsJSON
此 JSON 剖析之後會新增註釋至圖表。
ChartTitle、XLabel、YLabel、Y2Label
圖表和每根軸的標籤。如果未指定任何內容，則不會顯示標籤。邊框會自動新增至標籤文字的圖表。
DataLabel<#>
若指定，則會提供用於序列的標籤。如果保留為空白，JSONData 可提供資料標籤。如果 DataLabel<#> 已指定，則該序列無法使用第二個 Y 軸的功能。
DateWindowEnd 和 DateWindowStart
圖表顯示時，初始 X 軸範圍的開始時間和結束時間。
DisableVerticalZoom
選取此核取方塊後，會禁用圖表的垂直縮放。
EnableZoomSynchronizing
選取此核取方塊後，圖表可與另一個圖表同步處理其縮放。
HexColors
以逗號分隔的十六進位顏色值清單，用於圖表中顯示的序列資料，圖表中的每個序列均有一個值。例如：#a2a2a2,#f2b927,#3ec556,#09aec6,#ed684a,#a2a2a2。此屬性由服務用於動態設定序列顏色。如果未針對 HexColors 指定值，則會使用 SeriesStyle<#> 內容值。
HideSeries<#>InLegend
選取此核取方塊後，會從圖表圖例隱藏序列。
isZoomed
可讓您追蹤圖表目前是否已放大。對於混搭或服務端在處理不同的縮放使用案例 (在已縮放的情況下進行縮放，在已縮放以及保持縮放的情況下更新資料) 時，此功能特別有用。
JSONData
圖表中使用的資料為 JSON，以字串格式傳送。使用字串而非資料負載傳送資訊；原因在於資料負載逐行傳遞至小工具，需進一步操作資料才能將其提供給圖表。透過使用字串，可將資料一次就傳送到 Dygraph 資料庫以繪製圖表。此 JSON 的格式為 CSV。您可以使用 GenerateDygraphData 服務或使用會呼叫 GenerateDygraphData 的服務，將資料負載轉換為 CSV。若需進一步資訊，可參閱： http://dygraphs.com/data.html#csv。
已透過字串形式傳送至 GetJsonStringTrendHistory 服務之資料的範例：
{"isCustom":true,"trendType":"PerformanceHistory","displayId":
"Asset_CheeseCake_CleaningAndDryingMachine","endDate":1501819199000,
"startDate":1501732800000,"isZoomed":false,"zoomedMax":0,"zoomedMin":0}
SeriesVisibilities
包含圖表序列可見度設定的以逗號分隔的清單。每個清單項目的格式為 <序列索引>:<布林>，其中布林值用於指定序列是否可見。例如︰
0:true,1:true,2:false,3:false,4:true,5:false
此屬性由服務用於動態設定序列可見度。如果未針對 SeriesVisibilities 指定任何值，則會使用 SeriesVisibility<#> 內容值。
SeriesVisibility<#>
確定序列資料是否顯示於圖表中。此屬性對應圖表右側資訊面板中之序列的可見度選取項。
useValueRange、valueRangeMin 與 valueRangeMax
當選取 useValueRange 後，您可以為要呈現的 Y 軸設定最小 (valueRangeMin) 與最大 (valueRangeMax) 值。
zoomMax 和 zoomMin
當在圖表上執行縮放時，這些內容會使用 JSON 資料取得新值，指出取自於 X 軸的最大值與最小值。如果是使用 date-time 的資料格式，則通常是以毫秒 (ms) 為單位回傳時間。
此類屬性可在小工具的「樣式屬性」標籤中找到︰
內容
描述
SeriesStyle<#>
用於顯示於圖表中之序列資料的色彩，以及作為圖表右側資訊面板中的彩色方形的色彩。
SeriesSecondAxis<#>
確定序列的 Y 軸顯示在圖表左側還是右側。選取此核取方塊後，Y 軸會顯示在右側。清除此核取方塊後，Y 軸會顯示在左側。此屬性對應針對圖表右側資訊面板中之序列所選取的 Y 軸顯示選項 (左側或右側)。
下圖顯示了為 ChartTitle、XLabel、YLabel 和 Y2Label 所指定的值，以及將 ConnectSeparatedPoints 設定為 true 的範例。
Dygraph 小工具事件
此類事件可在「繫結」部分中小工具的「屬性」標籤中找到︰
事件
描述
DoubleClicked
執行連按兩下的動作時，會觸發此事件。連按兩下圖表後，會使用隨同資料提供的原始 zoomMin 與 zoomMax 值進行縮小處理。
SyncRequest
如果已啟用 EnableZoomSynchronizing 內容，則在執行放大或縮小動作時，會觸發此事件。使用此事件可同步處理另一圖形的縮放功能。此事件必須繫結至目標圖形的 sync 服務，才能進行同步。
Zoomed
執行縮放的動作時，會觸發此事件。使用此事件搭配 zoomMin 與 zoomMax，則可深入原始資料。
Dygraph 小工具服務
此類服務可在「繫結」部分中小工具的「屬性」標籤中找到︰
服務
描述
detach
呼叫後，目前混搭中的所有圖表不會同步處理。
dygraphSynchronize
呼叫後，目前混搭中的所有圖表將進行同步處理。無需其他組態。
resetZoom
手動將縮放重設回預設狀態。
sync
SyncRequest 事件的接收器，可在呼叫圖形時同步圖形的縮放。
當縮放時使用 CustomBars 以新增更多詳細資訊
對大型資料集執行平均化處理時，可能會遺失某些資訊。要解決此問題的方法之一，就是除了求解平均值之外，另外新增自訂範圍。如此會在圖表上的線條背後，產生透明的彩色範圍，即代表數值的範圍。舉例來說，若在趨勢詳細資訊圖表上選取「顯示值的範圍」，即可看到類似下列的顯示情形：
如果平均為 5 且數值是從 1 到 10，則線條會落在 5；透明範圍則顯示 1 到 10。若要使用此功能，請啟用 CustomBars 屬性並相應變更資料。
未啟用 CustomBars 之 JSON 資料的範例︰
Date,point1,point2
例如：
Date,trend1,trend2
2017-03-21,1,9
2017-03-22,2,2
2017-03-23,7,0
2017-03-24,3,5
啟用 CustomBars 之 JSON 資料的範例︰
Date,minPoint1;point1,maxPoint1,minPoint2;point2,maxPoint2;
例如：
Date,trend1,trend2
2017-03-21,0;1;8,4;9;9
2017-03-22,1;2;6,0;2;8
2017-03-23,5;7;9,0;0;4
2017-03-24,2;3;4,4;5;6
同步多個圖形之間的縮放層級
有兩種方法可同步多個圖形之間的縮放：
• 使用 Dygraphs 圖表資料庫功能（建議）—
此縮放同步處理會使用 Dygraphs 圖表資料庫中的完整資料庫應用功能和內建功能。若要瞭解詳細資訊，請參閱： http://dygraphs.com/gallery/#g/synchronize。
若要使用此縮放同步處理方法：
◦ 若要在載入混搭時同步處理頁面上的所有圖表，需為混搭中的所有圖表選取 DygraphSynchDefault 核取方塊。依預設，不會選取此核取方塊。
◦ 依需要使用 dygraphSynchronize 和 detach 服務來同步處理和取消同步處理目前頁面中的所有圖表。
• 使用 ThingWorx 功能—
若要同步多個圖形之間的縮放，則可使用來源圖形的 SyncRequest 事件，並將之繫結到目標圖形的 sync 服務。
選取來源小工具，將 SyncRequest 拖放到目標小工具上，並選取 sync 服務。
針對雙向縮放同步處理，則反向重複這些步驟。
互動式縮放
下列步驟即針對 ThingWorx Composer 中的 Dygraph 小工具，說明實行互動式縮放的流程。趨勢詳細資訊頁面上的圖表，就是此實行的範例。
1. 從原始的大型資料集合開始。
2. 如果資料集合過大，則應平均或減少圖表上資料點的數量。
3. 當使用者放大時，則應取得 zoomMin 與 zoomMax，並重新計算會使用此新範圍的資料，如步驟 2 中的驗證作業。如果資料點的數量夠少，則顯示原始資料；而不是平均或減少資料點的數量。
4. 當使用者縮小時，則依照其開始與結束時間，返回原始資料集合。
為圖例與標籤使用 CSS
使用 CSS 對圖表圖例與標籤的顯示進行格式化處理，可透過在混搭上提供自訂 CSS 取代此設定。此處有提供用於圖表圖例與標籤的預設 CSS，供您參考。如需詳細資訊，請參閱 ThingWorx 說明中心中的 「自訂 CSS」。
圖表圖例的預設 CSS︰
.dygraph-legend {
position: absolute;
z-index: 10;
font-family: Arial;
font-size: 10px;
opacity: 0.75;
border: 1px solid black
border-radius: 2px;
padding: 6px;
width: 300px; /* labelsDivWidth */
/*
dygraphs determines these based on the presence of chart labels.
It might make more sense to create a wrapper div around the chart proper.
top: 0px;
right: 2px;
*/
background: white;
line-height: normal;
text-align: left;
overflow: overlay;
left: 600px !important
}
.dygraph-legend-line {
display: inline-block;
position: relative;
bottom: .5ex;
padding-left: 1em;
height: 1px;
border-bottom-width: 2px;
border-bottom-style: solid;
/* border-bottom-color is set based on the series color */
}
標籤的預設 CSS︰
.dygraph-legend {
position: absolute;
z-index: 10;
font-family: Arial;
font-size: 10px;
opacity: 0.75;
border: 1px solid black
border-radius: 2px;
padding: 6px;
width: 300px; /* labelsDivWidth */
/*
dygraphs determines these based on the presence of chart labels.
It might make more sense to create a wrapper div around the chart proper.
top: 0px;
right: 2px;
*/
background: white;
line-height: normal;
text-align: left;
overflow: overlay;
left: 600px !important
}
.dygraph-legend-line {
display: inline-block;
position: relative;
bottom: .5ex;
padding-left: 1em;
height: 1px;
border-bottom-width: 2px;
border-bottom-style: solid;
/* border-bottom-color is set based on the series color */
}