配置

本页描述了可用于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 类是所有表单字段类（CWidgetFieldCheckBox、CWidgetFieldTextArea、CWidgetFieldRadioButtonList 等）的基类。继承 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	用于地图导航树小部件。在编辑模式下用地图选择树替换小部件视图。

Documentation

配置

小部件

WidgetForm

CWidgetFormView

JavaScript

CWidgetField