配置

此页面描述了可用于create具有自定义配置字段的widget配置视图的类。 widget 配置视图是 widget 的一部分，允许用户为 presentation 配置 widget 参数。

小部件

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

Widget 类应位于控件 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 字段，这些字段用于定义widget配置存储结构以及处理输入验证。

WidgetForm 类应当位于 includes 目录中。如果类使用了不同的名称，则应在 manifest.json 文件的小部件参数中指定该名称。

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 类，用于小部件get配置视图中。
addFieldset() - 接收一个 CWidgetFieldsGroupView 类的实例，该实例将字段组合成一个可折叠的容器。
addFieldsGroup() - 接收一个 CWidgetFormFieldsetCollapsibleView 的实例，该实例通过边框将字段组合成一个可视化的组。
includeJsFile() - 允许添加一个 JavaScript file 到小部件get配置视图中。
addJavaScript() - 允许添加内联 JavaScript，该脚本将在小部件get配置视图加载时立即执行。

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类应随表单一同加载，因此需在CWidgetFormView类中通过includeJsFile()和addJavaScript()方法进行引用。

以下示例中，单例类实例会立即创建并存储在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 类是一个基类，所有表单字段类（CWidgetFieldCheckBox、CWidgetFieldTextArea、CWidgetFieldRadioButtonList 等）均继承自该类。
继承自 CWidgetField 的类负责接收、保存和验证小部件get的配置值。

以下是可用的 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	多选字段，用于选择包含一个主机的数据源（仪表板或其他小部件），小部件get可以显示这些数据。
CWidgetFieldMultiSelectService	ID	多选字段，用于选择服务。
CWidgetFieldMultiSelectSla	ID	多选字段，用于选择SLA。
CWidgetFieldMultiSelectUser	ID	多选字段，用于选择用户。
CWidgetFieldNumericBox	string	输入float数字的字段。
CWidgetFieldRadioButtonList	int32	由一个或多个单选框组成的单选框组。
CWidgetFieldRangeControl	int32	用于选择integer类型值的滑块。
CWidgetFieldReference	string	为仪表板上的此小部件get创建唯一标识符。用于从其他小部件引用此小部件get。
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	用于地图导航树小部件。在编辑模式下用地图选择树替换小部件get视图。

Documentation

配置

小部件

WidgetForm

CWidgetFormView

JavaScript

CWidgetField