配置

本页介绍可用于创建具有自定义配置字段的小部件配置视图的类。小部件配置视图是小部件的一部分，允许用户为演示配置小部件参数。

小部件

主要小部件类，扩展所有仪表板小部件的基类 - CWidget。

覆盖默认小部件行为所需。

Widget 类应位于小部件的根目录中（例如，zabbix/ui/modules/my_custom_widget）。

Widget.php 示例

<?php
       
       命名空间 Modules\MyCustomWidget;
       
       使用 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 文件中的 widget/form_class 参数中指定该名称。

includes/WidgetForm.php 示例

<?php
       
       命名空间 Modules\MyCustomWidget\Includes;
       
       使用 Modules\MyCustomWidget\Widget;
       
       使用 Zabbix\Widgets\{
       CWidgetField,
       CWidgetForm
       };
       
       使用 Zabbix\Widgets\Fields\{
       CWidgetFieldMultiSelectItem,
       CWidgetFieldTextBox,
       CWidgetFieldColor
       };
       
       类 WidgetForm 扩展了 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'
       ];
       
       公共函数 addFields(): self {
       返回 $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 文件添加到小部件配置视图。
addJavaScript() - 允许添加内联 JavaScript，该 JavaScript 将在加载小部件配置视图后立即执行。

CWidgetFormView 类应位于 views 目录中。

views/widget.edit.php 示例

<?php
       
       /**
       * 我的自定义小部件表单视图。
       *
       * @var CView $this
       * @var array $data
       */
       
       use Modules\MyCustomWidget\Includes\WidgetForm;
       
       (新 CWidgetFormView($data))
       ->addField(
       (新 CWidgetFieldMultiSelectItemView($data['fields']['itemid']))->setPopupParameter('numeric', true)
       )
       ->addFieldset(
       (新 CWidgetFormFieldsetCollapsibleView(_('高级配置')))
       ->addField(
       新 CWidgetFieldTextBoxView($data['fields']['description'])
       )
       ->addField(
       新 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 名称下。因此，第二次打开表单将重新创建该实例。

JavaScript 类应位于 views 目录中。

views/widget.edit.js.php 示例

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

CWidgetField

CWidgetField 类是所有表单字段类（CWidgetFieldCheckBox、CWidgetFieldTextArea、CWidgetFieldRadioButtonList 等）都继承自该类的基类。

扩展 CWidgetField 的类负责接收、保存和验证小部件配置值。

可用的 CWidgetField 类如下。

CWidgetField 类	数据库字段类型	说明
CWidgetFieldCheckBox	int32	单个复选框。
CWidgetFieldCheckBoxList	int32 数组	单个配置字段下的多个复选框。
CWidgetFieldColor	字符串	颜色选择字段。
CWidgetFieldDatePicker	字符串	日期选择字段。
CWidgetFieldHostPatternSelect	string	允许选择一个或多个主机的多选字段。支持定义主机名模式（将选择所有匹配的主机）。
CWidgetFieldIntegerBox	int32	输入整数的字段。可用于配置最小值和最大值。
CWidgetFieldLatLng	string	允许输入逗号分隔的纬度、经度和地图缩放级别的文本框。
CWidgetFieldMultiSelectAction	ID	用于选择操作的多选字段（从Alerts → Actions中定义的操作列表中）。
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	用于输入浮点数的字段。
CWidgetFieldRadioButtonList	int32	由一个或多个单选框组成的单选框组。
CWidgetFieldRangeControl	int32	用于选择整数类型值的滑块。
CWidgetFieldReference	string	在仪表板上为此小部件创建唯一标识符。它用于从其他小部件引用此小部件。
CWidgetFieldSelect	int32	下拉选择框。
CWidgetFieldSeverities	int32 数组	CWidgetFieldCheckBoxList 预设触发严重性。
CWidgetFieldTags	（字符串、int32、字符串）数组	允许配置一个或多个标签过滤器行。
CWidgetFieldTextArea	字符串	用于输入多行文本的文本区域。
CWidgetFieldTextBox	字符串	用于输入单行文本的文本框。
CWidgetFieldTimePeriod	字符串数组	时间段选择字段。
CWidgetFieldTimeZone	字符串	带有时区的下拉菜单。
CWidgetFieldThresholds	（字符串、字符串）数组	允许配置颜色和数字对。
CWidgetFieldUrl	字符串	允许输入 URL 的文本框。

已为特定小部件创建了以下 CWidgetField 类。这些类具有非常具体的用例，但如果需要，也可以重复使用。

CWidgetField 类	数据库字段类型	说明
CWidgetFieldColumnsList	数组（多个混合）	用于顶级主机小部件。创建一个包含允许类型的自定义列的表格。
CWidgetFieldNavTree	字符串	用于地图导航树小部件。用地图选择树替换编辑模式下的小部件视图。

Documentation

配置

小部件

WidgetForm

CWidgetFormView

JavaScript

CWidgetField