## 表单组件
表单组件用于在 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`: 默认值
