配置

本页描述了可用于create小部件配置视图的类,这些类可添加自定义配置字段。 小部件配置视图是小部件的一部分,允许用户为presentation配置小部件参数。

小部件

主控件类,继承所有仪表板控件的基础类CWidget。 用于覆盖控件的默认行为。

Widget类应位于控件的根目录下(例如zabbix/ui/modules/my_custom_widget)。

Widget.php示例

<?php
       
       namespace Modules\MyCustomWidget;
       
       use Zabbix\Core\CWidget;
       
       class Widget extends CWidget {
       
           public const MY_CONSTANT = 0;
       
           public function getTranslationStrings(): array {
               return [
                   'class.widget.js' => [
                       'No data' => _('No data')
                   ]
               ];
           }
       }

WidgetForm

WidgetForm类继承自默认类CWidgetForm,包含一组用于定义数据库中小部件配置存储结构及处理输入验证的CWidgetField字段。

WidgetForm类应位于includes目录中。 若类名不同,则需在manifest.json小部件参数中通过file指定类名。

includes/WidgetForm.php 示例

<?php
       
       namespace Modules\MyCustomWidget\Includes;
       
       use Modules\MyCustomWidget\Widget;
       
       use Zabbix\Widgets\{
           CWidgetField,
           CWidgetForm
       };
       
       use Zabbix\Widgets\Fields\{
           CWidgetFieldMultiSelectItem,
           CWidgetFieldTextBox,
           CWidgetFieldColor
       };
       
       class WidgetForm extends CWidgetForm {
       
           public const DEFAULT_COLOR_PALETTE = [
               'FF465C', 'B0AF07', '0EC9AC', '524BBC', 'ED1248', 'D1E754', '2AB5FF', '385CC7', 'EC1594', 'BAE37D',
               '6AC8FF', 'EE2B29', '3CA20D', '6F4BBC', '00A1FF', 'F3601B', '1CAE59', '45CFDB', '894BBC', '6D6D6D'
           ];
       
           public function addFields(): self {
               return $this
                   ->addField(
                       (new CWidgetFieldMultiSelectItem('itemid', _('Item')))
                           ->setFlags(CWidgetField::FLAG_NOT_EMPTY | CWidgetField::FLAG_LABEL_ASTERISK)
                           ->setMultiple(false)
                   )
                   ->addField(
                       new CWidgetFieldTextBox('description', _('Description'))
                   )
                   ->addField(
                       (new CWidgetFieldColor('chart_color', _('Color')))->setDefault('FF0000')
                   );
           }
       }

CWidgetFormView

CWidgetFormView 类用于指定 WidgetForm 类中定义字段的呈现逻辑, 决定它们在配置视图中的外观和行为。

CWidgetFormView 类支持以下方法:

  • addField() - 接收 CWidgetFieldView 类的实例作为参数; 每个 CWidgetField 类都有对应的 CWidgetFieldView 类用于部件配置视图。
  • addFieldset() - 接收 CWidgetFieldsGroupView 类的实例,将字段组合成可折叠容器。
  • addFieldsGroup() - 接收 CWidgetFormFieldsetCollapsibleView 的实例,通过边框将字段视觉上组合成一组。
  • includeJsFile() - 允许向部件配置视图添加 JavaScript file。
  • addJavaScript() - 允许添加内联 JavaScript,这些代码将在部件配置视图加载后立即执行。

CWidgetFormView 类应位于 views 目录中。

views/widget.edit.php 示例

<?php
       
       /**
        * My custom widget form view.
        *
        * @var CView $this
        * @var array $data
        */
       
       use Modules\MyCustomWidget\Includes\WidgetForm;
       
       (new CWidgetFormView($data))
           ->addField(
               (new CWidgetFieldMultiSelectItemView($data['fields']['itemid']))->setPopupParameter('numeric', true)
           )
           ->addFieldset(
               (new CWidgetFormFieldsetCollapsibleView(_('Advanced configuration')))
                   ->addField(
                       new CWidgetFieldTextBoxView($data['fields']['description'])
                   )
                   ->addField(
                       new CWidgetFieldColorView($data['fields']['chart_color'])
                   )
           )
           ->includeJsFile('widget.edit.js.php')
           ->addJavaScript('my_custom_widget_form.init('.json_encode([
               'color_palette' => WidgetForm::DEFAULT_COLOR_PALETTE
           ]).');')
           ->show();

JavaScript

JavaScript类可用于为小部件配置视图添加动态行为和交互性。 例如,您可以初始化一个颜色选择器,该选择器定义在CWidgetFormView类中。

JavaScript类应随表单一起加载,因此应通过使用includeJsFile()addJavaScript()方法在CWidgetFormView类中引用它。

在下面的示例中,单例类实例会立即创建并存储在window.my_custom_widget_form名称下。 因此,第二次打开表单将重新create该实例。

JavaScript类应位于views目录中。

views/widget.edit.js.php示例

<?php
       
       use Modules\MyCustomWidget\Widget;
       
       ?>
       
       window.my_custom_widget_form = new class {
       
           init({color_palette}) {
               colorPalette.setThemeColors(color_palette);
       
               for (const colorpicker of jQuery('.<?= ZBX_STYLE_COLOR_PICKER ?> input')) {
                   jQuery(colorpicker).colorpicker();
               }
       
               const overlay = overlays_stack.getById('widget_properties');
       
               for (const event of ['overlay.reload', 'overlay.close']) {
                   overlay.$dialogue[0].addEventListener(event, () => { jQuery.colorpicker('hide'); });
               }
           }
       };

CWidgetField

CWidgetField 类是所有表单字段类(CWidgetFieldCheckBoxCWidgetFieldTextAreaCWidgetFieldRadioButtonList 等)的基类。 继承 CWidgetField 的类负责接收、保存和验证小部件配置值。

以下是可用的 CWidgetField 类。

CWidgetField 类 数据库字段类型 描述
CWidgetFieldCheckBox int32 单个复选框。
CWidgetFieldCheckBoxList array of int32 单个配置字段下的多个复选框。
CWidgetFieldColor string 颜色选择字段。
CWidgetFieldDatePicker string 日期选择字段。
CWidgetFieldHostPatternSelect string 多选字段,允许选择一个或多个 主机。支持定义 主机名 模式(所有匹配的 主机 将被选中)。
CWidgetFieldIntegerBox int32 用于输入 integer 的字段。可用于配置最小值和最大值。
CWidgetFieldLatLng string 文本框,允许输入以逗号分隔的纬度、经度和地图缩放级别。
CWidgetFieldMultiSelectAction ID 用于选择操作的多选字段(来自 告警 → 操作 中定义的操作列表)。
CWidgetFieldMultiSelectGraph ID 用于选择自定义图形的多选字段。
CWidgetFieldMultiSelectGraphPrototype ID 用于选择自定义图形原型的多选字段。
CWidgetFieldMultiSelectGroup ID 用于选择 主机 组的多选字段。
CWidgetFieldMultiSelectHost ID 用于选择 主机 的多选字段。
CWidgetFieldMultiSelectItem ID 用于选择 监控项 的多选字段。
CWidgetFieldMultiSelectItemPattern ID 用于选择 监控项 模式的多选字段。
CWidgetFieldMultiSelectItemPrototype ID 用于选择 监控项原型 的多选字段。
CWidgetFieldMultiSelectMap ID 用于选择地图的多选字段。
CWidgetFieldMultiSelectMediaType ID 用于选择媒介类型的多选字段。
CWidgetFieldMultiSelectOverrideHost ID 用于选择包含 一个主机 的数据源(仪表板或其他小部件)的多选字段,小部件可以显示这些数据。
CWidgetFieldMultiSelectService ID 用于选择服务的多选字段。
CWidgetFieldMultiSelectSla ID 用于选择 SLA 的多选字段。
CWidgetFieldMultiSelectUser ID 用于选择用户的多选字段。
CWidgetFieldNumericBox string 用于输入 float 数字的字段。
CWidgetFieldRadioButtonList int32 由一个或多个单选按钮组成的单选按钮组。
CWidgetFieldRangeControl int32 用于选择 integer 类型值的滑块。
CWidgetFieldReference string 为仪表板上的此小部件创建唯一标识符。用于从其他小部件引用此小部件。
CWidgetFieldSelect int32 下拉选择框。
CWidgetFieldSeverities array of int32 带有触发器严重性的 CWidgetFieldCheckBoxList 预设。
CWidgetFieldTags array of (string, int32, string) 允许配置一个或多个标签过滤行。
CWidgetFieldTextArea string 用于输入多行文本的文本区域。
CWidgetFieldTextBox string 用于输入单行文本的文本框。
CWidgetFieldTimePeriod array of string 时间段选择字段。
CWidgetFieldTimeZone string 带有时区的下拉框。
CWidgetFieldThresholds array of (string, string) 允许配置颜色和数字对。
CWidgetFieldUrl string 允许输入 URL 的文本框。

以下 CWidgetField 类是为特定小部件创建的。 这些类有非常具体的用例,但也可以根据需要重用。

CWidgetField 类 数据库字段类型 描述
CWidgetFieldColumnsList array of (multiple mixed) 用于 Top 主机 小部件。创建具有允许类型的自定义列的表格。
CWidgetFieldNavTree string 用于 地图导航树 小部件。在编辑模式下用地图选择树替换小部件视图。