概述

介绍

所有物联网仪表板都是使用 YiCONNECT 小部件构建的。

小部件是在仪表板上显示特定类型的信息或功能的元素。小部件用于显示从连接到 YiCONNECT 平台的设备获取的数据和可视化信息、远程设备控制、警报管理以及显示静态自定义 HTML 内容。

小部件类型

小部件有五种类型：

时间序列小部件显示特定时间窗口的数据。它可以是实时 - 某个最新间隔的动态变化的时间范围，也可以是历史 - 固定的历史时间范围。时间序列小部件的示例是图表小部件。显然，时间序列小部件旨在显示时间序列而不是属性；
最新值小部件显示特定属性或时间序列键的最新值。例如，设备型号或最新温度读数；
控制小部件允许您向设备发送RPC 命令。例如，在恒温器装置上控制所需的温度；
警报小部件允许您显示警报；
静态小部件旨在显示静态数据。例如，平面图或静态公司信息。

每个小部件通常都有特定的设置和参数，允许用户根据自己的需要自定义其行为和外观。

本指南涵盖主要概念和各种小部件设置。

将小部件添加到仪表板

要将新的小部件添加到仪表板，您应该：

打开仪表板并进入编辑模式；
单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“选择小部件捆绑包”对话框窗口;
选择一个小部件包，例如“图表”。要快速找到所需的小部件，请通过单击放大镜图标并输入小部件的名称来使用搜索栏；
选择一个小部件，例如“时间序列折线图”，然后单击它以打开“添加小部件”对话框窗口；
指定数据源，添加数据键，然后单击“添加”按钮。最后，应用您的更改；
您的第一个小部件已创建。

小部件设置

小部件设置由一个或多个数据源、外观设置、小部件卡设置、操作和移动设备外观组成，您可以对小部件的内容进行自定义和执行。

请注意 ，仅严格要求数据源配置。在大多数情况下，您可以将所有其他配置选项卡保留为默认值。

在创建小部件期间，您可以在基本功能和高级功能之间进行选择。模式之间的切换是在小部件创建窗口的右上角完成的。

基本功能

当您使用单一数据源类型而无需附加条件或过滤器时，基本功能适合快速启动。它包括时间窗口的设置、数据源选择（实体别名或设备）以及小部件外观的一组基本设置，这取决于小部件的用途。

先进的功能

在高级功能中，您可以使用多个数据源（如果小部件支持）并应用过滤器，它包括五个选项卡用于更详细的小部件配置：数据、小部件卡、操作和移动。

此外，在高级功能中，还有其他可用的数据源类型：函数、实体计数和警报计数（并非所有小部件都支持这些数据类型）。

数据设置

小部件时间窗口

小部件时间窗口定义了用于获取时间序列或警报数据的时间间隔和聚合函数。默认情况下，每个小部件都使用仪表板工具栏中确定的主时间窗口。您可以通过将选项切换为“使用小部件时间窗口”参数来覆盖默认时间窗口。您还可以使用“显示时间窗口”复选框向用户隐藏特定小部件的时间窗口选择。

数据源类型

Widget数据设置用于添加一个或多个数据源。数据源是数据源类型、实体别名、可选过滤器和数据键列表（实体时间序列）的组合。基本上，数据源决定应使用哪些实体（别名和过滤器）小部件以及为这些实体获取哪些数据键。

数据源主要分为三种类型： Device 、Entity和 Function 。

此外，对于某些小部件（例如价值卡），还有其他数据源类型，例如实体计数和 警报计数 。

下面，我们将讨论每种类型。

设备作为数据源

指定设备作为数据源将从指定设备检索数据。

假设您有一个发布室内温度值的设备，并且您希望在小部件上显示这些数据。让我们使用温度计刻度小部件可视化此数据。

打开仪表板并进入编辑模式。然后单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“小部件捆绑包”对话窗口；
选择“模拟仪表”小部件包；
然后选择一个“温度计刻度”小部件；
将打开“添加小部件”对话框窗口。选择数据源类型 - “设备”并选择您的设备。然后添加数据键-“温度”。单击“添加”并保存所有更改；
温度计刻度小部件已创建。

请注意 ，在这种情况下，数据源只能是单个设备。

实体作为数据源

将实体指定为数据源将从指定的实体别名获取数据。

让我们使用一个基本示例来熟悉此功能，在小部件上显示所有现有设备。

打开仪表板并进入编辑模式。然后单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“小部件捆绑包”对话窗口；
选择“表格”小部件包；
然后选择一个“实体表”小部件；
将打开“添加小部件”对话框窗口。选择数据源类型 - “实体”。现在，我们需要创建一个新的实体别名。单击实体别名行中的“新建”按钮；
在打开的“添加别名”对话框中，输入别名，选择过滤器类型 - “实体类型”，然后选择实体类型 - “设备”。点击“添加”；
添加数据键。然后点击“添加”并保存所有更改；
添加了一个小部件，用于显示使用实体别名作为数据源的所有设备。

作为数据源的功能

当您没有任何数据，但您想测试小部件可视化时，可以使用函数作为数据源。假设您尚未添加别名，也未收到任何遥测数据，但您想查看小部件如何显示数据。

打开仪表板并进入编辑模式。然后单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“小部件捆绑包”对话窗口；
选择“卡片”小部件包；
然后选择一个“Value card”小部件；
将打开“添加小部件”对话框窗口。导航到高级功能并选择数据源类型 - “随机”。然后添加一个功能——“随机”，点击“随机”键的“铅笔”图标，打开数据键配置窗口；
将标签名称更改为“温度”并指定单位。点击“保存”；
单击“添加”并保存所有更改；
创建了显示随机值的值卡小部件。

实体数量

实体数量允许您通过在小部件上显示实体来查看实体的数量，从而确定设备、资产等的数量。

让我们通过一个基本示例来熟悉此功能，在小部件上显示现有设备的总数。

打开仪表板并进入编辑模式。然后单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“小部件捆绑包”对话窗口；
选择“卡片”小部件包；
然后选择一个“Value card”小部件；
将打开“添加小部件”对话框窗口。转到高级功能并选择数据源类型 - “实体计数”。现在，我们需要创建新的实体别名。单击实体别名行中的“新建”按钮；
在打开的“添加别名”对话框中，输入别名，选择过滤器类型 - “实体类型”，然后选择实体类型 - “设备”。点击“添加”；
在数据键行中点击“计数”键的“铅笔”图标，打开数据键配置窗口；
将标签名称更改为“设备数”并指定单位。点击“保存”；
最后，点击“添加”并保存所有更改；
现在我们有一个小部件来显示现有设备的数量。

警报计数

警报计数允许您在小部件上显示来自您的所有设备和客户设备的警报总数。

让我们通过一个基本示例来熟悉此功能，在小部件上显示现有警报的总数。

打开仪表板并进入编辑模式。然后单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“小部件捆绑包”对话窗口；
选择“卡片”小部件包；
然后选择一个“Value card”小部件；
将打开“添加小部件”对话框窗口。转到高级功能，选择数据源类型 - “警报计数”并指定过滤器。在数据键行中点击“计数”键的“铅笔”图标，打开数据键配置窗口；
将标签名称更改为“警报计数”并指定单位。点击“保存”；
最后，单击“添加”并应用更改；
现在我们有一个小部件，可以显示现有设备的所有警报。

数据键

数据键定义您想要在小部件中使用的时间序列、属性或实体字段。数据键定义由类型（时间序列、实体字段属性）和实际键组成。

可用属性键列表基本上是设备或其他实体的所有客户端、服务器和共享属性的列表。

可用时间序列键的列表取决于您的设备向 YiCONNECT报告的时间序列数据或您通过规则引擎或REST API保存的时间序列数据。

实体字段列表取决于实体类型，并且将来可能会扩展：

设备、资产和实体视图具有以下字段：创建时间、实体类型、名称、类型、标签、附加信息。
用户具有以下字段：创建时间、名字、姓氏、电子邮件和其他信息。
客户具有以下字段：创建时间、实体类型、电子邮件、标题、国家/地区、状态、城市、地址、邮政编码、电话、附加信息。

数据源的数据键列表取决于小部件类型：

时间序列小部件允许选择时间序列数据键。此外，您还可以配置timewindow；
最新值小部件允许选择时间序列、属性和实体字段；
静态和控制小部件不需要数据密钥；
警报小部件允许选择所有数据键：时间序列、属性、实体和警报字段。此外，您还可以配置时间窗口和警报过滤器。

要将时间序列或属性键添加到数据源，请单击数据键行并从下拉菜单中选择所需的键。

假设您在数据库中还没有所需的时间序列或属性键。在这种情况下，您仍然可以向数据源添加密钥，一旦设备将数据发送到 YiCONNECT，小部件就会开始显示数据。为此，请单击数据键行，然后输入名称并选择未来键的类型：属性、实体字段或时间序列。

在高级小部件设置中，数据键可以配置为两种不同的模式：常规和高级。两种模式都提供独特的配置选项。

通用数据键配置

数据键配置根据小部件类型及其接受的数据类型而有所不同。在常规设置中，某些小部件允许您修改键的名称和颜色、调整标签名称、在值旁边添加特定字符（Timeseries 键除外）、定义小数精度以及切换“使用后处理功能” ” 开或关。

如果您使用添加新小部件的基本功能，则可以在小部件创建窗口中直接使用这些设置。

如果您使用高级功能添加新小部件，请单击数据键行中某个键的“铅笔”图标以打开完整的数据键设置。

基本数据关键配置

让我们看一下基本数据键设置，这是“Tables”捆绑包中“Entities table”小部件的示例：

钥匙。 您可以更改密钥的名称。在这种情况下，将显示密钥的数据，即您在“密钥”行中指定的密钥名称。更改密钥的名称并单击“保存”。

请注意： 键有四种类型：属性、时间序列、实体字段和警报字段（仅适用于警报小部件）。为了正确显示数据，请将键名更改为现有的同类型键名。如果数据库中还没有所需的时间序列或属性键，您仍然可以向数据源添加键。一旦设备将数据发送到 YiCONNECT，小部件就会开始显示数据。

标签。 在您的小部件中，数据列的名称是标签名称。根据需要更改标签名称，然后单击对话框窗口右下角的“保存”。

单位。 您可以指示将显示在值旁边的特殊符号。在单位字段中输入所需的字符，然后单击“保存”。

小数点。 指定浮点数后要显示的位数，然后单击“保存”。

颜色。 每个键都分配有不同的颜色。在某些小部件（例如图表）中，小部件中显示的图形线的颜色就是键的颜色。您可以更改按键的颜色。单击彩色圆圈，选择所需的标签颜色，然后按“选择”。

密钥聚合

默认情况下，最新值小部件没有时间窗口。 如果您在“最新值 ”小部件中启用任何数据键的聚合，则会出现时间窗口控件。您可以为每个遥测密钥单独设置聚合，您想要显示这些密钥，同时不需要将其存储在数据库中。时间窗口配置仅限于实时间隔（ 当前小时/天/月 ）和“ 历史 ”时间间隔。出于性能原因，不支持“过去 30 分钟”或“过去 24 小时”等实时间隔。

聚合选项：

最小值或 最大值 ：选择给定间隔的最小值或最大值。用于检测峰值负值或正值。例如，电力电缆中的电涌、空气污染、设备工作负荷等。

平均值： 计算所选间隔的平均值（汇总，然后除以所选间隔的遥测计数）。例如，您可以使用平均聚合来计算每周燃油消耗、以 dB 为单位的噪音、风扇转速、信号质量等。

Sum： 汇总指定时间段内的所有遥测数据。例如，聚合用于不同类型的遥测、里程（公里）、耗水量、闲置时间等。

计数： 计算选定时间段内传输的消息总数。它可用于设置和优化使用电池供电的设备或评估传感器激活灵敏度等。

德尔塔函数：

允许您计算当前时间窗口间隔和相对时间窗口间隔的聚合值之间的增量。

比较周期 ——是以历史区间为基础，根据选择的选项进行换算的参数。下面的选项列表。

上一个间隔 （默认）- 设置为默认选项，计算时不仅考虑时间，还考虑间隔类型（当前日期或当前日期等）示例： 历史记录 -当前月份到目前为止选项，假设间隔为 1.09.22 到 25.09.22，则前一个间隔将为 1.08.22 到 25.08.22

一天前 - 从历史记录间隔的开始和结束开始，需要 24 小时。例如，当日和Delta -天前的用水量：

一周前 - 采用比历史间隔早一周的间隔（168 小时）。平均值、历史间隔示例 -当前日期和一周前增量：

一个月前 - 与历史间隔相同的间隔（以天为单位）并从当前历史间隔中减去。例如，如果当前月份是 2 月（28 天），则“ 上个月” 将是前 28 天，而不是上个月的整个月份。例如，使用总水量、历史记录 -当前日期和Delta - 一个月前 ：

一年前 - 当前历史记录间隔 365 天前的间隔。如果需要比较的话，假设上个月和去年月份的合计。

自定义间隔 - 此选项用于设置独立的间隔。最大允许值仅限于int类型。示例：43200000 = 12 小时。

Delta计算结果：

此选项允许您指定结果的显示方式：

上一个值 - 显示比较间隔的聚合值（不是当前历史间隔）。
Delta（绝对） - 显示比较间隔之间的差异，此选项是默认设置的。
Delta（百分比） - 将结果显示为相对于上一个间隔公式的百分比：(IntervalValue - prevIntervalValue)/prevIntervalValue*100

使用数据后处理功能。 数据后处理功能允许根据您的意愿更改输出数据。要使用数据后处理功能，必须勾选“使用数据后处理功能”复选框，并在下面的字段中输入该功能。然后点击右下角的“保存”按钮。

高级数据密钥设置

高级数据键配置负责小部件上特定数据键列的可见性、样式和外观。实体表小部件、警报表小部件和实体管理小部件捆绑包具有相同的高级数据密钥配置。图表小部件包有其自己独特的高级数据键配置。所有其他小部件包仅具有基本数据密钥配置。

报警过滤器

警报小部件允许您根据状态、严重性和类型过滤警报。您可以选择警报状态和严重性的组合。您还可以定义特定的警报类型以及启用传播警报的搜索。

外貌

假设您仅使用小部件数据配置步骤添加了“Timeseries Line Chart”小部件来显示温度计。您应该看到类似的小部件（请注意，您应该发送/模拟一些数据以查看图表中的实际线条）：

让我们使用基本的小部件设置来自定义小部件。我们将演示每个设置如何影响小部件。

数据设置

您可以选择值旁边显示的符号以及浮点数后的位数。如果您想对所有轴应用相同的设置，这些设置非常有用。例如，如果您要显示多个设备的温度读数，则可以添加“°C”或“°F”符号。但是，如果您同时显示温度和湿度，则必须使用数据键设置单独配置这些数据键。

您还可以指定在小部件没有传入数据时将显示的替代消息。当数据到达时，消息将消失并显示传入的数据。

您可以在小部件设置的“ 高级 ”功能、“ 外观 ”选项卡中找到这些设置。

常用设置

堆叠方式

此选项与“Timeseries Bar Chart”小部件相关。堆叠模式功能显示求和的实体值以防止重叠，每个值都通过唯一的颜色进行区分。仅当数据聚合功能未设置为 None 时，才能使用此功能。如果不激活“启用堆叠模式”，条形将根据所使用实体的值进行分割。要查看所有实体的值，您需要将鼠标悬停在栏上。

如果您需要从堆叠中排除特定密钥，请转至高级数据密钥配置，然后选中“从堆叠中排除”复选框。

图例设置

默认情况下，图表小部件启用“显示图例”选项。此图例显示统计值，包括最小值、最大值、平均值和总计。相反，其他小部件没有启用此选项。

启用图例后，您可以灵活地：

选择图例的方向和位置；
选择要包含的数据值（最小值、最大值、平均值、总计）；
选择对数据键进行排序或保持不排序。

您可能会注意到图例显示每个配置的数据键的数据键标签。当同一个小部件中有来自多个设备的数据时，很难在图例或工具提示中找到哪个设备对应于哪个记录。为了使图例和工具提示清晰，您应该在数据键配置中使用 ${entityName} 或${entityLabel} 。

轴设置

配置首选轴参数。

指定垂直轴和水平轴的标题，并设置最小和最大比例值。

您还可以设置刻度颜色、小数位数以及刻度之间的步长。

纵轴设置 ：

水平轴设置 ：

刻度格式化函数，f(值)

假设我们有遥测数据，它需要非常大的数字值，特别是当值附近有特殊符号时。但是，我们需要构建一个小图表（因为仪表板上没有很多可用空间）。因此，使用ticks-formatter函数，我们可以将ticks值转换为更紧凑的形式。

return value.toExponential(1) + " C";

图表背景设置

您可以更改图表网格的外观：自定义背景颜色、网格框架及其刻度，以及关闭线条可见性。

工具提示设置

将鼠标悬停在各个点上 。当选中“悬停单个点”框时，您将不会在线上看到值点。
以堆叠模式显示累积值 。当堆叠模式打开时，您可以选中“累积值”框以使图表显示所有实体值的总和。

当你想要手动自定义工具提示时，使用工具提示值格式函数，f(value,latestData) 。

您可以通过工具提示设置或高级数据键配置自定义将在工具提示中显示的值。通过设置进行的工具提示配置是基本的，并且同时应用于所有实体。在高级数据键配置中配置时，仅适用于特定时间序列数据，基本工具提示功能将被该配置覆盖。

在状态图中，您可以根据实体值将实体状态配置为显示在工具提示上。

让我们使用该函数将值从摄氏度转换为华氏度并并排显示这些值：

let celsiusValue = parseFloat(value).toFixed(2);
let farenheitValue = parseFloat(celsiusValue*1.8 + 32).toFixed(2);
return celsiusValue + ' °C (' + farenheitValue + ' °F)';

在工具提示值格式函数字段中，输入工具提示函数，然后应用更改；
将鼠标悬停在小部件上可查看带有应用值格式功能的工具提示。

比较设置

您可以显示要比较的历史数据。

在“外观”选项卡中，切换“启用比较”复选框，然后从下拉菜单中选择显示要比较的历史数据的时间。在“比较 X 轴设置”部分中，选择轴位置，比较轴将位于小部件上。此外，您还可以输入轴标题并显示轴刻度标签；
导航到“数据”选项卡，然后单击数据键行中某个键的“铅笔”图标；
在数据键配置窗口中，导航至“高级”选项卡并选择比较线颜色。完成比较设置配置后，应用更改；
由于比较设置仅在历史时间窗口模式下有效，因此单击仪表板工具栏中的“编辑时间窗口”图标，转到“历史”选项卡，然后选择要比较当前数据的时间间隔。然后点击“更新”进行应用；
现在您可以比较当前分钟和五分钟前的值。

自定义图例设置

当您需要展示不适合图表表示的数据（例如特定属性）时，或者当您只想在图表图例中显示某些时间序列时，请使用自定义图例设置。例如，考虑可以在表格小部件中显示但不能在图表上显示的活动/非活动属性。

导航到“外观”选项卡。激活“启用自定义图例”选项以使用属性或时间序列值作为关键标签。单击“+ 添加新密钥”。在出现的下拉菜单中输入按键名称并选择按键类型；
进入“数据”选项卡。单击数据密钥旁边的铅笔图标可访问数据密钥配置窗口；
在标签行中，输入模式 ${} 并将数据键名称放在括号内。单击“保存”设置新标签名称并应用所有更改；
现在，当您查看小部件时，您将看到自定义图例设置已应用。

小部件卡

小部件标题设置

您可以输入自定义小部件标题、工具提示和标题样式。您还可以向标题添加图标并控制图标颜色和大小。请参阅下面的配置和相应的结果。

上面屏幕上的标题样式：

{
  "fontSize":"15px",
  "fontWeight":600
}

小部件样式设置

您可以使用 CSS 属性自定义小部件的个人风格。此样式将应用于小部件的主 div 元素。

您还可以使用“投影”复选框禁用小部件阴影，并使用“启用全屏”复选框禁用全屏。默认情况下启用所有这些设置。

您还可以更改背景颜色、文本颜色、填充和边距。请参阅下面的配置和相应的结果。

请注意，样式和背景颜色只是一个示例，绝对不是我们指南的一部分。

上面屏幕上的小部件样式：

{
  "border":"3px solid #2E86C1",
  "cursor":"pointer"
}

小部件按钮设置

启用全屏

您可以使用“启用全屏”复选框禁用全屏。默认情况下启用此设置。

默认情况下启用所有这些设置。

导入和导出小部件

导入小部件

您可以从 JSON 文件导入小部件。

要导入小部件，您应该：

打开仪表板并进入编辑模式。然后单击屏幕顶部的“+ 添加小部件”图标，或者（如果这是此仪表板上的第一个小部件）单击屏幕中间的大“添加新小部件”标志以打开“选择小部件捆绑包”对话框窗户;
点击屏幕右上角的“导入小部件”按钮；
在小部件导入窗口中，上传JSON文件并点击“导入”；
小部件已导入。但是，由于未指定数据源，小部件尚未显示数据。进入Edit widget模式，指定数据源；
指定数据源、添加数据键并应用更改；
您现在应该在小部件中看到数据。在我们的例子中，这是一个温度图。完成所有设置后，保存仪表板。

导出小部件

要导出小部件，您应该转到小部件所在的仪表板。然后进入“编辑模式”。现在，在所需小部件的右上角，单击“导出小部件”按钮。此操作将 JSON 格式的配置文件以及特定小部件的所有设置保存到您的 PC。