[comment]: # aside:1 [comment]: # ({0a11f1a9-f7477fb0}) # 配置 本页介绍可用于创建具有自定义配置字段的小部件配置视图的类。 小部件配置视图是小部件的一部分，允许用户为[演示](/presentation) 配置小部件参数。 [comment]: # ({/0a11f1a9-f7477fb0}) [comment]: # ({68bbd84a-adf59b13}) ### 小部件 主要小部件类，扩展所有仪表板小部件的基类 - *CWidget*。 覆盖默认小部件行为所需。 *Widget* 类应位于小部件的根目录中（例如，*zabbix/ui/modules/my_custom_widget*）。 **Widget.php 示例** ```php [ 'No data' => _('No data') ] ]; } } ``` [comment]: # ({/68bbd84a-adf59b13}) [comment]: # ({e5aad37e-1ff26877}) ### WidgetForm *WidgetForm* 类扩展了默认类 *CWidgetForm*，并包含一组 [*CWidgetField*](#cwidgetfield) 字段 这些字段是定义数据库中的小部件配置存储结构和处理输入验证所必需的。 *WidgetForm* 类应位于 *includes* 目录中。 如果该类具有不同的名称，则应在 *manifest.json* 文件中的 [*widget/form_class*](/devel/modules/file_structure/manifest#widget) 参数中指定该名称。 **includes/WidgetForm.php 示例** ```php 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') ); } } ``` [comment]: # ({/e5aad37e-1ff26877}) [comment]: # ({3ca7a0e4-61f06fc3}) ### CWidgetFormView *CWidgetFormView* 类是指定 *WidgetForm* 类中定义的字段的呈现逻辑所必需的， 确定它们在配置视图中呈现时的外观和行为。 *CWidgetFormView* 类支持以下方法： - *addField()* - 接收 *CWidgetFieldView* 类的实例作为参数； 每个 [*CWidgetField*](#cwidgetfield) 类都有一个相应的 *CWidgetFieldView* 类，用于小部件配置视图。 - *addFieldset()* - 接收 *CWidgetFieldsGroupView* 类的实例，该类将字段组合成可折叠容器。 - *addFieldsGroup()* - 接收 *CWidgetFormFieldsetCollapsibleView* 的实例，该实例以视觉方式（带边框）将字段组合成一个组。 - *includeJsFile()* - 允许将 JavaScript 文件添加到小部件配置视图。 - *addJavaScript()* - 允许添加内联 JavaScript，该 JavaScript 将在加载小部件配置视图后立即执行。 *CWidgetFormView* 类应位于 *views* 目录中。 **views/widget.edit.php 示例** ```php 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(); ``` [comment]: # ({/3ca7a0e4-61f06fc3}) [comment]: # ({d7c94075-d1c62429}) ### JavaScript JavaScript 类可用于向小部件配置视图添加动态行为和交互性。 例如，您可以初始化在 [*CWidgetFormView*](#cwidgetformview) 类中定义的颜色选择器。 JavaScript 类应随表单一起加载，因此应使用方法 *includeJsFile()* 和 *addJavaScript()* 在 [*CWidgetFormView*](#cwidgetformview) 类中引用它。 在下面的示例中，立即创建了一个单例类实例，并将其存储在 *window.my_custom_widget_form* 名称下。 因此，第二次打开表单将重新创建该实例。 JavaScript 类应位于 *views* 目录中。 **views/widget.edit.js.php 示例** ```php window.my_custom_widget_form = new class { init({color_palette}) { colorPalette.setThemeColors(color_palette); for (jQuery('. 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'); }); } } }; ``` [comment]: # ({/d7c94075-d1c62429}) [comment]: # ({1e4be89d-708ecb6b}) ### CWidgetField *CWidgetField* 类是一个基类，所有表单字段类（*CWidgetFieldCheckBox*、*CWidgetFieldTextArea*、*CWidgetFieldRadioButtonList* 等）都继承自该类。 扩展 *CWidgetField* 的类负责接收、保存和验证部件配置值。 以下是可用的 *CWidgetField* 类。 |CWidgetField 类|数据库字段类型|描述| |----|----|----------| |*CWidgetFieldCheckBox*|int32|单个复选框。| |*CWidgetFieldCheckBoxList*|array of int32|单个配置字段下的多个复选框。| |*CWidgetFieldColor*|string|颜色选择字段。| |*CWidgetFieldDatePicker*|string|日期选择字段。| |*CWidgetFieldIntegerBox*|int32|用于输入整数的字段。可用于配置最小值和最大值。| |*CWidgetFieldLatLng*|string|允许输入以逗号分隔的纬度、经度和地图缩放级别的文本框。| |*CWidgetFieldMultiSelect*|-|多选字段的基类，所有 *CWidgetFieldMultiSelect\** 类都继承自它。| |*CWidgetFieldMultiSelectAction*|ID|用于从 *Alerts → Actions* 中定义的动作列表中选择动作的多选字段。| |*CWidgetFieldMultiSelectGraph*|ID|用于选择自定义图形的多选字段。| |*CWidgetFieldMultiSelectGraphPrototype*|ID|用于选择自定义图形原型的多选字段。| |*CWidgetFieldMultiSelectGroup*|ID|用于选择主机组的多选字段。| |*CWidgetFieldMultiSelectHost*|ID|用于选择主机的多选字段。| |*CWidgetFieldMultiSelectHostInventory*|array of int32|用于选择主机资产记录字段的多选字段。| |*CWidgetFieldMultiSelectItem*|ID|用于选择监控项的多选字段。| |*CWidgetFieldMultiSelectItemPrototype*|ID|用于选择监控项原型的多选字段。| |*CWidgetFieldMultiSelectMap*|ID|用于选择地图的多选字段。| |*CWidgetFieldMultiSelectMediaType*|ID|用于选择媒介类型的多选字段。| |*CWidgetFieldMultiSelectOverrideHost*|ID|用于从仪表板或其他部件中为主机选择数据源的多选字段。| |*CWidgetFieldMultiSelectService*|ID|用于选择服务的多选字段。| |*CWidgetFieldMultiSelectSla*|ID|用于选择 SLA 的多选字段。| |*CWidgetFieldMultiSelectUser*|ID|用于选择用户的多选字段。| |*CWidgetFieldNavTree*|array of (multiple mixed)|存储地图的导航树结构，用于 *Map navigation tree* 部件。| |*CWidgetFieldNumericBox*|string|用于输入浮点数的字段。| |*CWidgetFieldPatternSelect*|-|模式选择字段的基类，所有 *CWidgetPatternSelect\** 类都继承自它。| |*CWidgetFieldPatternSelectHost*|string|用于选择主机的多选字段。支持主机名模式。| |*CWidgetFieldPatternSelectItem*|string|用于选择监控项的多选字段。支持监控项名称模式。| |*CWidgetFieldRadioButtonList*|int32|由一个或多个单选框组成的单选框组。| |*CWidgetFieldRangeControl*|int32|用于选择整数类型值的滑块。| |*CWidgetFieldReference*|string|存储该部件在仪表板上的唯一标识符；用于部件间通信。| |*CWidgetFieldSelect*|int32|下拉选择框。| |*CWidgetFieldSeverities*|array of int32|预设了触发器严重性的 *CWidgetFieldCheckBoxList*。| |*CWidgetFieldSparkline*|array of (multiple mixed)|允许配置迷你趋势图。| |*CWidgetFieldTags*|array of (string, int32, string)|允许配置一个或多个标签过滤器行。| |*CWidgetFieldTextArea*|string|用于输入多行文本的文本区域。| |*CWidgetFieldTextBox*|string|用于输入单行文本的文本框。| |*CWidgetFieldThresholds*|array of (string, string)|允许配置颜色和数字对。| |*CWidgetFieldTimePeriod*|array of string|时间段选择字段。| |*CWidgetFieldTimeZone*|string|带有时区的下拉列表。| |*CWidgetFieldUrl*|string|允许输入 URL 的文本框。| ::: noteclassic `int32` 字段的最大长度为 10 个字符，`ID` 字段为 20 个字符，`string` 字段为 65535 个字符。 对于复合类型（例如 `array of (string, int32, string)`），该限制分别适用于每个元素。 可使用 `setMaxLength()` 等方法设置字段特定的长度限制。 ::: [comment]: # ({/1e4be89d-708ecb6b})