Dygraph 小组件

自定义信息展示方式 > ThingWorx 应用程序小组件 > Dygraph 小组件

Dygraph 小组件

Dygraph 小组件用于显示各种时间序列图表。在 ThingWorx Apps 中，该组件在多处使用：

• 在“趋势分析和故障排除”中，出现在趋势详细信息页面 (PTC.Factory.TrendTroubleshooting.TrendDetail)

• 在 Controls Advisor 中，作为“客户端计数”和“标记计数趋势”图表 (PTC.Factory.KEPServerEX.DetailPage)

• 在“生产 KPI”中，作为“状况历史记录”和“KPI 趋势”图表出现在“生产历史记录数据”页面 (PTC.Factory.ProductionHistoricalData、PTC.Factory.C_ProductionHistoricalData_[发布版本])

• 在 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_[发布版本] 混搭中小组件的服务：

• 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 轴的最小和最大值)。如果使用日期-时间数据格式，通常以毫秒为单位返回时间。

这些属性位于该小组件“样式属性”选项卡上：

特性	说明
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 设置。这里是图表图例和标签的默认 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：