>[info] 從1.0.6開始，支持自定義擴展表單項 | 版本 | 新增功能 | | --- | --- | | 1.0.7 | 支持調用公共資源 | | 1.1.0 | 修改靜態資源位置，如果是從舊版升級到1.1.0，則請參考[升級指導](升級指導.md)，將對于的資源移動到public目錄 | >[danger] ### 注意，以下教程僅適用于1.1.0版本以前的，如果框架版本為1.1.0以上，則自定義表單項的靜態資源不能放在`extend\form`下，需要放在`\public\extend\form`。具體請參考[升級指導](升級指導.md) 雖然目前ZBuilder提供了超過30種表單項，但還是不足以滿足用戶的需求。為此，我們對表單構建器進行了功能擴展，讓開發者可以自己定義表單項。 由于剛支持該功能，可能有些地方還不夠人性化或者滿足需求，所以在使用中若有什么更好的建議，歡迎到[論壇](http://bbs.dolphinphp.com/)發帖。 下面介紹如何擴展表單項，這里以擴展“顏色選擇器”來作為演示。雖然ZBuilder本身已經有“顏色選擇器”，但我們這次用自定義擴展的方式實現相同的功能。 ### 1.建立表單項目錄 首先，我們在目錄：`extend\form`下新建一個目錄，名字就`test`。這個目錄名稱就是我們要擴展的表單項類型名稱。 >[danger] 注意，目錄名為全小寫，并且不要和已存在的表單項類型沖突。  ### 2.放入顏色選擇器需要的文件（可選） 這一步是可選的，如果你創建的表單項無需依賴任何js或css，可以跳過這一步。因為顏色選擇器需要依賴一些js和css文件，所以要把相關的文件放在該目錄下。  ### 3.建立入口文件 接著，我們在`test`目錄下創建名稱為`Builder.php`的入口文件，這個文件名是固定的，必須為`Builder.php`。 然后我們需要在該入口文件中，創一個`item`方法，這個方法是用于在調用ZBuilder時供使用者調用的方法。 ~~~ <?php namespace form\test; class Builder { /** * 取色器 * @param string $name 表單項名 * @param string $title 標題 * @param string $tips 提示 * @param string $default 默認值 * @param string $mode 模式：默認為rgba(含透明度)，也可以是rgb * @param string $extra_attr 額外屬性 * @param string $extra_class 額外css類名 * @author 蔡偉明 <314013107@qq.com> * @return mixed */ public function item($name = '', $title = '', $tips = '', $default = '', $mode = 'rgba', $extra_attr = '', $extra_class = '') { return [ 'name' => $name, 'title' => $title, 'tips' => $tips, 'value' => $default, 'mode' => $mode, 'extra_class' => $extra_class, 'extra_attr' => $extra_attr, ]; } } ~~~ >[info] 命名空間固定為`form\表單項名` `item`方法的參數是自定義的，你的表單項需要用到什么參數，就寫什么參數，根據實際情況來寫。它需要返回一個數組，這個數組就是你在模板中需要用到的數據。如果需要在這里么進行一些判斷或者處理，都是可以的，只要最終反回一個數組即可。 >[danger] 需要注意的是，返回的數據中，必須包含name，而且不得包含鍵為`type`的數組元素，系統會自動添加上對應的`type`，比如上面的代碼，實際上輸出到頁面時，會自動添加上`type => 'test'`。 ### 4.定義需要加載的js和css文件（可選） 這一步也是可以選的，如果你的表單項并不依賴任何js或css文件，可以忽略這一步。 ~~~ <?php namespace form\test; class Builder { /** * 取色器 * @param string $name 表單項名 * @param string $title 標題 * @param string $tips 提示 * @param string $default 默認值 * @param string $mode 模式：默認為rgba(含透明度)，也可以是rgb * @param string $extra_attr 額外屬性 * @param string $extra_class 額外css類名 * @author 蔡偉明 <314013107@qq.com> * @return mixed */ public function item($name = '', $title = '', $tips = '', $default = '', $mode = 'rgba', $extra_attr = '', $extra_class = '') { return [ 'name' => $name, 'title' => $title, 'tips' => $tips, 'value' => $default, 'mode' => $mode, 'extra_class' => $extra_class, 'extra_attr' => $extra_attr, ]; } /** * @var array 需要加載的js */ public $js = [ 'bootstrap-colorpicker/bootstrap-colorpicker.min.js', 'test.js' // 默認加載當前表單項目錄下的test.js ]; /** * @var array 需要加載的css */ public $css = [ 'bootstrap-colorpicker/css/bootstrap-colorpicker.css' ]; } ~~~ 在這里，我們加入了兩個js文件，一個是顏色選擇器的js文件，一個是用來創建顏色選擇器的js文件。另外加入了一個css樣式文件。 >[info] ### 如果是1.0.7版本以上，則可以使用模板變量替換來調用公共資源 ~~~ public $js = [ '__LIBS__/bootstrap-colorpicker/bootstrap-colorpicker.min.js', 'test.js' ]; ~~~ 表示引用`/public/static/libs/bootstrap-colorpicker/bootstrap-colorpicker.min.js`，更多資源路徑請參考[變量參考](變量參考.md) `test.js`內容如下： ~~~ $(document).ready(function () { jQuery('.js-colorpicker').each(function(){ var $colorpicker = jQuery(this); var $colorpickerMode = $colorpicker.data('colorpicker-mode') ? $colorpicker.data('colorpicker-mode') : 'hex'; var $colorpickerinline = $colorpicker.data('colorpicker-inline') ? true : false; $colorpicker.colorpicker({ 'format': $colorpickerMode, 'inline': $colorpickerinline }); }); }); ~~~ ### 5.創建表單項模板文件 入口文件寫好后，我們需要創建一個模板文件，用來輸出內容。因為我們擴展的表單項類型為`test`，所以模板文件名必須為`test.html`。 代碼如下： ~~~ <div class="form-group col-xs-12 {$extra_class|default=''}" id="form_group_{$name}"> <label class="col-xs-12" for="{$name}">{$title|htmlspecialchars}</label> <div class="col-sm-12"> <div class="js-colorpicker input-group" data-colorpicker-mode="{$mode == '' ? 'rgba' : $mode}"> <input class="form-control" type="text" id="{$name}" name="{$name}" value="{$value|default=''}" placeholder="請從右邊選擇顏色" {$extra_attr|default=''}> <span class="input-group-addon"><i style="background-color: rgb(92, 144, 210);"></i></span> </div> {notempty name="tips"} <div class="help-block">{$tips}</div> {/notempty} </div> </div> ~~~ ### 6.調用表單項方法 自此，所有準備工作已經完成，接下來就是使用我們自定義的表單項了，完整的表單項目錄是這樣的。  因為我們定義的表單項類型為`test`，所以在ZBuilder中可以直接使用`->addTest()`來創建表單項，add接上類型名稱首字母大寫。 ~~~ return ZBuilder::make('form') ->addTest('color', '取色器') ->fetch(); ~~~  也可以用->addFormItem()方法 ~~~ return ZBuilder::make('form') ->addFormItem('test', 'color', '取色器') ->fetch(); ~~~ 或者->addFormItems()方法 ~~~ return ZBuilder::make('form') ->addFormItems([ ['text', 'username', '用戶名'], ['test', 'color', '取色器'] ]) ->fetch(); ~~~  當然，也支持布局，但需要在模板中添加一段代碼 >[info]`col-md-{$_layout|default='12'}` `test.html`最終是這樣的 ~~~ <div class="form-group col-md-{$_layout|default='12'} {$extra_class|default=''}" id="form_group_{$name}"> <label class="col-xs-12" for="{$name}">{$title|htmlspecialchars}</label> <div class="col-sm-12"> <div class="js-colorpicker input-group" data-colorpicker-mode="{$mode == '' ? 'rgba' : $mode}"> <input class="form-control" type="text" id="{$name}" name="{$name}" value="{$value|default=''}" placeholder="請從右邊選擇顏色" {$extra_attr|default=''}> <span class="input-group-addon"><i style="background-color: rgb(92, 144, 210);"></i></span> </div> {notempty name="tips"} <div class="help-block">{$tips|clear_js}</div> {/notempty} </div> </div> ~~~ >[danger] 注意：1.1.0版本以上，模板中的布局代碼需要改成 >` col-xs-{$_layout.xs|default='12'}` >如果需要在不同的屏幕尺寸顯示不同大小，那么需要添加多幾個 >`col-xs-{$_layout.xs|default='12'} col-sm-{$_layout.sm|default='12'} col-md-{$_layout.md|default='12'} col-lg-{$_layout.lg|default='12'}` 然后我們就可以使用布局參數了 ~~~ return ZBuilder::make('form') ->addText('username', '用戶名') ->addTest('color', '取色器') ->layout(['color' => 6]) ->fetch(); ~~~  當然，也可以這樣。 ~~~ return ZBuilder::make('form') ->addText('username', '用戶名') ->addFormItem('test:6', 'color', '取色器') ->fetch(); ~~~ 或者這樣 ~~~ return ZBuilder::make('form') ->addFormItems([ ['text', 'username', '用戶名'], ['test:6', 'color', '取色器'] ]) ->fetch(); ~~~ 也可以放在表單分組中。 ~~~ return ZBuilder::make('form') ->addText('username', '用戶名') ->addGroup([ '分組1' => [ ['test', 'color', '取色器'] ], '分組2' => [ ['text', 'nickname', '昵稱'] ] ]) ->fetch(); ~~~  >[danger] ### 注意，如果框架版本為1.1.0以上，則自定義表單項的靜態資源不能放在`extend\form`下，需要放在`\public\extend\form`。具體請參考[升級指導](升級指導.md)