配置

此页面描述了可用于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 的类负责接收、保存和验证 widget 配置值。

可用的 CWidgetField 类如下。