创建部件

本章节以创建 customBtn 部件为例阐述创建部件的详细过程。

前置步骤

创建目录和文件

1. 创建 lib/zin/wg/custombtn/ 目录；
2. 创建 lib/zin/wg/custombtn/v1.php 文件。

开启严格模式

<?php
declare(strict_types=1);

设置命名空间

namespace zin;

所有部件的命名空间均为 zin。

创建部件类

声明部件类

class customBtn extends wg
{

}

所有部件都继承自基类 wg，wg 类中定义了许多属性与方法，customBtn 类通过重写这些属性与方法实现部件。

定义部件属性

部件属性是用户在部件实例上设置的数据。通常部件上可供设置的属性由部件设计时决定，大部分情况下开发者可以选择性的设置这些属性。部件在渲染时会根据实际的属性数据决定如何渲染从而实现多种个性化功能。

接下来将为 customBtn 部件设置了几个属性并规定每个属性的必填性、数据类型以及默认值。

当属性的默认值为基本类型（如 int、string、bool 等）时，可通过 defineProps 属性一并设置：

protected static $defineProps = array(
    'text:string',
    'type?:string="button"',
    'disabled?:bool=false'
);

它等同于：

protected static $defineProps = array(
    'text:string',
    'type?:string',
    'disabled?:bool'
);

protected static $defaultProps = array(
    'disabled' => false,
    'type'     => 'button'
);

但当属性的默认值为复杂类型（如 array、object）时，必须通过 defaultProps 属性设置。

定义内部块

内部块是 zin 部件的一种特殊属性，它允许用户设置部件内部不同的内容区域，这样可以方便的将内容插入到指定的位置。

接下来将定义一个名为 prefix 的内部块，它将现实在在按钮文本前，它可以是数据或文字，也可以是一个部件（如 icon 部件）。

具体代码如下：

protected static $defineBlocks = array(
    'prefix' => array()
);

实现 build 方法

protected function build(): wg
{
    $text        = $this->prop('text');
    $type        = $this->prop('type');
    $disabled    = $this->prop('disabled');
    $prefixBlock = $this->block('prefix');

    return button
    (
        set::type($type),
        set::disabled($disabled),
        setClass('primary'),
        $prefix, //使用内部块
        $text
    );
}

build 方法为部件最核心的方法，它定义了本部件最终所渲染的 DOM 结构。

加载外部 css

部件内的样式优先通过 zui3 工具类实现，此外可以通过加载外部 css 文件的方式实现自定义部件样式。

具体步骤如下：

1. 创建目录 lib/zin/wg/custombtn/css；
2. 创建文件 lib/zin/wg/custombtn/css/v1.css;
3. 在 lib/zin/wg/custombtn/v1.css 文件中编写样式；
4. 实现 getPageCSS() 静态方法加载外部 css，具体代码如下：

public static function getPageCSS()
{
    return file_get_contents(__DIR__ . DS . 'css' . DS . 'v1.css');
}

加载外部 js

部件同样支持加载外部 js 文件实现事件绑定等功能。

具体步骤如下：

1. 创建目录 lib/zin/wg/custombtn/js/；
2. 创建文件 lib/zin/wg/custombtn/js/v1.js;
3. 在 lib/zin/wg/custombtn/v1.js 文件中编写函数；
4. 实现 getPageJS() 静态方法加载外部 js，具体代码如下：

public static function getPageJS()
{
    return file_get_contents(__DIR__ . DS . 'js' . DS . 'v1.js');
}

定义部件函数

由于 zin 部件通过类实现，在页面上使用部件的时候需要实例化一个部件类（在本例为 new customBtn(...) ）。

为了简化调用，可以在 lib/zin/func.php 文件中封装一个函数实现部件类的实例化，具体代码如下：

/**
 * Custom button wg.
 *
 * string  text           按钮文本
 * ?string type='button'  按钮类型
 * ?bool   disabled=false 是否禁用按钮
 *
 * ====== blocks ======
 * prefix = array()
 * ====================
 */
function customBtn()
{
    return createWg('customBtn', func_get_args());
}

进阶

可参考部件 API wg 一章了解 wg 类更多的属性和方法，通过使用、重写这些属性和方法可以创建更为复杂的部件。