Table of Contents
配置
本页描述了可用于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 | 用于 地图导航树 小部件。在编辑模式下用地图选择树替换小部件视图。 |