## 表單組件
表單組件用于在 update 或 add 頁面生成對應的表單項, 表單組件繼承`app\common\component\FormComponent`
### 常用組件說明
#### Input 基礎組件
用于生成基礎的 Input
##### 參數
無
##### 示例
```php
public $updateFields = [
'name' => ['text', 'require'], // 如無法找到對應的組件將默認使用 input 組件, 并且組件名將作為 input 的類
'price' => ['input', 'require'],
];
```
#### Area 地區選擇器
用于生成一個地區選擇器
##### 參數
`type`: 類型, 目前支持 `province`, `city`, `area` , 使用 `city` 類型必須要有一個同組的 `province` 類型, 使用`area` 類型需要有一個同組的 `city` 類型 和 一個同組的 `province`
`group`: 分組id, `group` 相同的才能產生交互效果
##### 示例
```php
public $updateFields = [
'province' => ['area', 'require', null, [
'type' => 'province',
'group' => 1
]],
'city' => ['area', null, null, [
'type' => 'city',
'group' => 1
]],
'target_province' => ['area', 'require', null, [
'type' => 'province',
'group' => 2
]],
'target_city' => ['area', 'require', null, [
'type' => 'city',
'group' => 2
]]
];
// 這里用到了兩組 area 組件, 所以需要設置 group, 一般情況下, 如果只有一組 area 就不需要設置 group
```
#### Checkbox 多選組件
生成一個多選的 checkbox
##### 參數
`table`: 使用該參數的表的查詢結果作為選擇項
`field`: 需要用到的字段, 當 `format` 參數為空時, 只能填寫一個字段, 并且該字段將作為選擇項顯示的內容
`value`: 作為值的字段
`format`: 展示的格式, 該字段存在時, `field` 參數可以是多個字段, "hello \*field\*" 中 "\*field\*" 將會被替換成字段 field 的值
`join`: 數據庫查詢時 join 的規則, 同 `think\Db::join` 方法參數格式相同
`where` 數據庫查詢時 where 的規則, 同 `think\Db::where` 方法參數格式相同
`list`: 當該參數存在時, 將使用該數據作為查詢的結果, `list` 與 `table` 只能存在一個
##### 示例
```php
public $addFields = [
'role_node.nid' => ['checkbox', 'require', null, [
'table' => 'node',
'field' => 'module, controller, action',
'value' => 'id',
'format' => '/*module*/*controller*/*action*'
]],
];
```
#### Hidden 隱藏域
生成一個隱藏的 input
##### 參數
無
##### 示例
```php
public $updateFields = [
'price' => ['hidden', 'require'],
];
```
#### Html 富文本
生成一個富文本編輯器
##### 參數
無
##### 示例
```php
public $updateFields = [
'information' => ['html'],
];
```
#### Image 圖片選擇
生成一個圖片上傳工具, 支持多選
##### 參數
無
##### 示例
```php
public $updateFields = [
'thumb' => ['image', 'require'],
'banners' => 'image',
];
```
#### Password 密碼組件
生成一個密碼類型的 input, **該組件在未填寫時將該字段從需要寫入數據庫的數組中刪除, 并且不會將數據庫對應字段的值渲染到前端**
##### 參數
無
##### 示例
```php
// 編輯賬號信息時賬號可以留空, 留空則不會修改原始密碼
public $updateFields = [
'password' => ['password', null, '無需修改的話, 請勿填寫!'],
];
// 添加賬號時必須填寫密碼
public $addFields = [
'password' => ['password', 'require'],
];
```
#### Readonly 只讀屬性
生成一個只讀的 input, **該組件不會將內容傳至后端, 一般僅用作展示內容**
##### 參數
無
##### 示例
```php
public $updateFields = [
'create_time' => 'readonly',
];
```
#### Selector 選擇器
生成一個單選的 select, **用法和參數與 checkbox 組件完全相同**
##### 參數
`table`: 使用該參數的表的查詢結果作為選擇項
`field`: 需要用到的字段, 當 `format` 參數為空時, 只能填寫一個字段, 并且該字段將作為選擇項顯示的內容
`value`: 作為值的字段
`format`: 展示的格式, 該字段存在時, `field` 參數可以是多個字段, "hello \*field\*" 中 "\*field\*" 將會被替換成字段 field 的值
`join`: 數據庫查詢時 join 的規則, 同 `think\Db::join` 方法參數格式相同
`where` 數據庫查詢時 where 的規則, 同 `think\Db::where` 方法參數格式相同
`list`: 當該參數存在時, 將使用該數據作為查詢的結果, `list` 與 `table` 只能存在一個
##### 示例
```php
public $updateFields = [
'$1.rid' => ['selector', 'require', null, [
'table' => 'role',
'field' => 'name',
'value' => 'id'
]],
];
```
#### Textarea 多行文本
生成一個多行文本的 textarea
##### 參數
無
##### 示例
```php
public $updateFields = [
'description' => 'textarea'
];
```
### 自定義表單組件
**閱讀該說明前請先確認你已經看過了 [視圖組件.md](視圖組件.md) 和 [搜索組件.md](搜索組件.md)中的自定義搜索組件**
與自定義表單組件相同, 如果默認提供的組件無法滿足你的需求, 你也可以像[搜索組件.md](搜索組件.md)中的自定義搜索組件中一樣
可以使用一個模板作為組件
也可以創建自己的表單組件
#### 使用模板作路徑為組件名
第一種方式與[搜索組件.md](搜索組件.md)相同, 只有模板變量的定義不同:
##### 模板變量說明:
`fieldName`: 字段展示名,
`field`: 字段名
`msg`: 提示信息
`value`: 數據庫對應字段的值, **只有在 update 頁面時才有, 使用時先判斷**
`data`: 組件參數, 由于該值是可選的, 使用前請先判斷是否存在,
`def`: 默認值
#### 創建自己的表單組件
該方法也與 [搜索組件.md](搜索組件.md) 類似, 表單組件命名前綴為 `Form` 所有的表單組件需要繼承 `app\common\component\FormComponent`
表單組件的類中有用于處理表單返回值的 `getParam` 方法, 定義如下:
```php
abstract class FormComponent extends Component
{
/**
* 獲取表單返回值
* @param $value mixed 表單返回值
* @param $key string 字段名
* @param $data array 完整的表單數組
* @return mixed
*/
public static function getParam ($value, $key = null, &$data = null)
{
if ($key !== null && $data !== null) $data[$key] = $value;
return $value;
}
}
```
**如需對返回值做特殊處理, 請重寫該方法**
##### 表單組件的模板變量定義如下:
`fieldName`: 字段展示名,
`field`: 字段名
`msg`: 提示信息
`value`: 數據庫對應字段的值, **只有在 update 頁面時才有, 使用時先判斷**
`data`: 組件參數, 由于該值是可選的, 使用前請先判斷是否存在,
`def`: 默認值