20. 组件

概览

Zabbix支持通过添加第三方组件或自研的组件来增强Zabbix前端的功能，而无需更改Zabbix的源代码。

需要注意的是组件代码将被赋予与Zabbix源代码相同的权限运行。这意味着：

• 第三方组件可能对zabbix环境产生损害。您必须安装可信任的组件；

• 第三方组件代码中的错误可能会导致前端崩溃。如果发生这种情况，只需从前端删除组件代码即可。当Zabbix前端重新加载完成后，您将看到一行表明组件被禁用的注释。在Module administration（administration→general→modules）中再次点击Scan directory可以从数据库中删除不生效的组件。

安装

请务必阅读特定组件的安装手册。建议逐个安装新的组件以便于捕捉安装过程中的失败信息。

在安装组件之前：

• 应确保所有下载的组件是从可信来源获取的，否则安装带有恶意代码的组件可能会导致数据丢失等后果。

• 不同版本的同一组件（相同ID）允许并行安装，但同一时间只允许启用单一版本的组件。

组件安装步骤：

• 将您的组件解包至自己的文件夹中，放入Zabbix前端modules文件夹下。

• 应确保您的组件文件夹中至少包含manifest.json文件。

• 前往Module administration并单击Scan directory 按钮。

• 新的组件将与其版本、作者、描述和状态一起出现在组件列表中。

• 单击其状态启用组件。

故障排除：

组件开发

组件是基于PHP语言编写的，建议使用Zabbix模型-视图-控制器（MVC）软件设计模式，好处在于其同时也应用于Zabbix前端，有利于后续开发。我们推崇使用PHP严格模式进行开发，但这并非强制性的要求。

请注意，您可以通过组件功能轻松地在Zabbix前端中添加新的菜单项以及对应各自的视图和操作，但暂时无法通过组件功能注册新的API或创建新的数据库表。

组件结构

每个组件都包含一个单独的目录（位于​modules​目录中），其子目录包含控制器、视图和任何其他代码：

example_module_directory/           (必须)
    manifest.json                   (必须)  元数据和操作定义。
    Module.php                                  组件初始化和事件处理。
    actions/                                    操作控制器文件。
        SomethingView.php
        SomethingCreate.php
        SomethingDelete.php
        data_export/                                 
            ExportAsXml.php
            ExportAsExcel.php
    views/                                      视图文件。
        example.something.view.php
        example.something.delete.php
        js/                                     使用在视图中的JavaScript文件。
            example.something.view.js.php
    partials/                                   视图局部文件。
        example.something.reusable.php
        js/                                     使用在局部中的JavaScript文件。
            example.something.reusable.js.php

显而易见，自定义组件目录中唯一的强制要求需包含的配置文件是​manifest.json​，没有此配置文件，组件将无法注册。​Module.php​负责注册菜单项并处理诸如“onBeforeAction”和“onTerminate”之类的事件。​actions、​views​和​partials​目录中包含组件操作所需的PHP和JavaScript代码。

命名约定

在创建组件之前，首当其冲的是要统一不同组件项之间（如组件目录和文件）的命名约定，这样我们就可以使这些组件项的名称井然有序，通俗易懂。您也可以在 module_structure找到示例。

请注意，’​module’​前缀对于视图和部分文件名是必需的，除非您需要覆盖Zabbix核心视图或部分文件，该条规则不适用于操作文件命名。

Manifest配置文件准备

每个组件都需要一个包含以下JSON格式的Manifest.json配置文件

详情可参见 reference中manifest.json配置文件说明的部分。

操作

组件会对manifest.json配置文件里​actions​对象定义的前端操作进行控制，使用这个方法可以定义新的操作，同样可以对已有操作进行定义。每个操作的键值都应该表示操作名称，相应的值应该包含​class​键和可选的​layout​键和​view​键。

一个操作由四个对应项定义：名称、控制器、视图和布局。数据验证和数据准备工作通常在控制器中完成，格式化输出在视图或局部视图中完成，布局则主要负责用菜单、页眉、页脚等元素装饰前端页面。

组件操作必须在manifest.json配置文件的​actions​对象中进行定义。

目前已经有一些预定义好的布局，例如​layout.json​或​layout.xml​。这些预定义的布局可用于产生与HTML不同效果的操作。您可以在app/​views/​directory目录下浏览预定义的布局，甚至可以创建自己的布局。

有时为了保持控制器的完整性而单独重定义部分操作的视图是有必要的。这种情况下只需要把必要的视图或局部文件放在组件的​views​目录下即可。

请参考Reference部分中的动作控制器文件示例。请尽情探索现有Zabbix操作的源代码，位于app/​目录中。

Module.php

这个可选的PHP文件负责模块初始化和事件处理，’​Module’​类应在此文件中定义，包括扩展基类​\Core\CModule​。’​Module’​类必须遵循manifest.json配置文件中的命名规范。

<?php
namespace Modules\Example;
use Core\CModule as BaseModule;
class Module extends BaseModule {
    ...
}

详情请参考Module.php在Reference中描述的部分。

参考示例

本章节包含前面几个章节中介绍的不同组件元素的基础版本。

manifest.json

{
    "manifest_version": 1.0,
    "id": "example_module",
    "name": "Example module",
    "version": "1.0",
    "namespace": "Example",
    "author": "John Smith",
    "url": "http://module.example.com",
    "description": "Short description of the module.",
    "actions": {
        "example.something.view": {
            "class": "SomethingView",
            "view": "module.example.something.view"
        },
        "example.something.create": {
            "class": "SomethingCreate",
            "layout": null
        },
        "example.something.delete": {
            "class": "SomethingDelete",
            "layout": null
        },
        "example.something.export.xml": {
            "class": "data_export/ExportAsXml",
            "layout": null
        },
        "example.something.export.excel": {
            "class": "data_export/ExportAsExcel",
            "layout": null
        }
    },
    "config": {
        "username": "john_smith"
    }
}

Module.php

<?php declare(strict_types = 1);
namespace Modules\Example;
use APP;
use CController as CAction;
/**
 * 有关其他参考，请参阅Core\CModule类。
 */
class Module extends \Core\CModule {
    /**
     * 组件初始化。
     */
    public function init(): void {
        // 初始化主菜单（CMenu类实例）。
        APP::Component()->get('menu.main')
            ->findOrAdd(_('Reports'))
                ->getSubmenu()
                    ->add((new \CMenuItem(_('Example wide report')))
                        ->setAction('example.report.wide.php')
                    )
                    ->add((new \CMenuItem(_('Example narrow report')))
                        ->setAction('example.report.narrow.php')
                    );
    }
    /**
     * 事件句柄，在执行操作前触发。
     *
     * @param CAction $action  负责当前请求的操作实例。
     */
    public function onBeforeAction(CAction $action): void {
    }
    /**
     * 事件句柄，应用退出时触发。
     *
     * @param CAction $action  负责当前请求的操作实例。
     */
    public function onTerminate(CAction $action): void {
    }
}

操作控制器

<?php declare(strict_types = 1);
namespace Modules\Example\Actions;
use CControllerResponseData;
use CControllerResponseFatal;
use CController as CAction;
/**
 * 操作组件示例。
 */
class SomethingView extends CAction {
    /**
     * 初始化操作。Zabbix核心调用方法。
     *
     * @return void
     */
    public function init(): void {
        /**
         * 禁用SID（Sessoin ID）验证。会话ID验证只能用于涉及数据修改的操作，如更新或删除操作。
         * 在这种情况下，必须在URL中显示会话ID，这样一旦会话过期，URL就会立即过期。
         */
        $this->disableSIDvalidation();
    }
    /**
     * 检查并清除用户输入参数。Zabbix核心调用方法。 如果返回false，则执行停止。
     *
     * @return bool true on success, false on error.
     */
    protected function checkInput(): bool {
        $fields = [
            'name'  => 'required|string',
            'email' => 'required|string',
            'phone' => 'string'
        ];
        // 只有经过验证的数据才能进一步使用$this->hasInput()和$this->getInput()。
        $ret = $this->validateInput($fields);
        if (!$ret) {
            $this->setResponse(new CControllerResponseFatal());
        }
        return $ret;
    }
    /**
     * 检查用户是否具有执行此操作的权限。Zabbix核心调用方法。
     * 如果返回false，则执行停止。
     *
     * @return bool
     */
    protected function checkPermissions(): bool {
        $permit_user_types = [USER_TYPE_ZABBIX_ADMIN, USER_TYPE_SUPER_ADMIN];
        return in_array($this->getUserType(), $permit_user_types);
    }
    /**
     * 准备视图的响应对象。Zabbix核心调用方法。
     *
     * @return void
     */
    protected function doAction(): void {
        $contacts = $this->getInput('email');
        if ($this->hasInput('phone')) {
            $contacts .= ', '.$this->getInput('phone');
        }
        $data = [
            'name' => $this->getInput('name'),
            'contacts' => $contacts
        ];
        $response = new CControllerResponseData($data);
        $this->setResponse($response);
    }
}

操作视图

<?php declare(strict_types = 1);
/**
 * @var CView $this
 */
$this->includeJsFile('example.something.view.js.php');
(new CWidget())
    ->setTitle(_('Something view'))
    ->addItem(new CDiv($data['name']))
    ->addItem(new CPartial('module.example.something.reusable', [
        'contacts' => $data['contacts']
    ])
    ->show();