## addLinkage('name值', '标题', '提示', '选项', '默认值', '异步请求地址' [, '后代name值', '请求参数名', '额外表单项值'])
标识符:`linkage`
| 版本 | 功能 |
| --- | --- |
| 1.3.3 | 支持发送额外表单项值 |
| 参数 | 含义 | 类型 |
| --- | --- | --- |
| name | name值 | string |
| title | 标题 | string |
| tips | 提示 | string |
| options | 选项 | array |
| default | 默认值 | string |
| ajax_url | 异步请求地址 | string |
| next_items | 后代name值 | string |
| param | 请求参数名 | string |
| extra_param| 额外表单项值(1.3.3+) | string |
### 先来个栗子感受一下
比如做个省份城市联动,这里最后一级是城市,没有地区。
~~~
$list_province = ['gd' => '广东', 'gx' => '广西'];
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city')
->addSelect('city', '选择城市')
->fetch();
~~~
效果:
![](https://box.kancloud.cn/6cddb07cc9181d0a8c51427c5ed401e8_1201x171.png)
下面,来讲解一下如何使用。
### 选项
比如上面的省份,“选项”是一个一维数组,和之前单选、复选等类型一样。
### 异步请求地址
是指选择下拉之后,去请求下级数据的地址,可以使用url函数生成或者直接写有效的url地址。
>[info] 返回的数据格式是json格式,并且里至少面要包含“code”、“msg”、“list”,其中,“code”表示状态,1表示获取成功,0表示获取失败。“msg”是提示信息,“list”是返回的列表数据。
一个典型的数据返回例子(这个例子只是简单的演示,无论传什么值过来,都返回相同的json数据)
~~~
// 根据省份获取城市
public function get_city($province = '')
{
$arr['code'] = '1'; //判断状态
$arr['msg'] = '请求成功'; //回传信息
$arr['list'] = [
['key' => 'gz', 'value' => '广州'],
['key' => 'sz', 'value' => '深圳'],
]; //数据
return json($arr);
}
~~~
>[info]“list”数组中,每一个数组元素需包含两个键,“key”和“value”,也可以借助format_linkage()方法将普通的一维数组转换为符合普通联动的数据结构。
### 后代name值
指子级下拉菜单的name值,比如上面的例子,省份的name值是“province”,城市的name值是`city`,那么需要给省份下拉菜单指定下级的name值,即`city`。
~~~
$list_province = ['gd' => '广东', 'gx' => '广西'];
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city')
->fetch();
~~~
如果是三级联动,那么“后代name值”就必须把所有子代下拉菜单的name值都写进去,并且以英文逗号隔开,比如加多一个地区:
~~~
$list_province = ['gd' => '广东', 'gx' => '广西'];
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city,area')
->addLinkage('city', '选择城市', '', '', '', url('get_area'), 'area')
->addSelect('area', '选择地区')
->fetch();
~~~
我们可以看到,选择省份中写的是“city,area”,而选择城市写的是“area”,选择地区则没有。
细心的朋友可能已经看出在第一个例子中,“选择城市”使用的是`addSelect`方法,而在这里使用的是`addLinkage`方法,最后一项“选择地区”用`addSelect`方法。
是的,最后一项是不用去获取数据的,所以我们可以用简单的`addSelect`方法即可,最终效果如下:
![](https://box.kancloud.cn/c1314a94daad09a53831cc29e0ddcbbf_1182x314.png)
### 请求参数名
默认情况下,选择下拉菜单后,去获取数据时会带上选中的数值,比如选择“广东”,就会给`get_city`方法传一个参数名为“province”,值为“gd”的参数。那么我们就可以在`get_city($province = '')`接收到这个参数,并查询数据库。
在没有修改的情况下,参数名是该下拉菜单的name值,如果有需要,可以修改为其他,比如:
~~~
$list_province = ['gd' => '广东', 'gx' => '广西'];
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city,area', 'sf')
->addLinkage('city', '选择城市', '', '', '', url('get_area'), 'area')
->addSelect('area', '选择地区')
->fetch();
~~~
那么`get_city`方法就不能用`province`来接收参数值,而是用`sf`,如:`get_city($sf = '')`,当然,使用`$this->request->post('sf')`也是可以获取到的。
### 额外表单项值(1.3.3+)
以上面的代码为例子,默认情况下,当我们选择城市时,会将城市的值发送给服务器,以获取地区列表。但有时候,我们希望能同时发送表单上的其他表单项值,那么就需要配置`extra_param`参数。
~~~
$list_province = ['gd' => '广东', 'gx' => '广西'];
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city,area', 'sf')
->addLinkage('city', '选择城市', '', '', '', url('get_area'), 'area', '', 'province')
->addSelect('area', '选择地区')
->fetch();
~~~
上面再添加选择城市中,最后一个参数设置为了`province`,那么在选择城市的时候,不仅会将城市代码发送到服务器,同时还会将当前选中的省份代码也发送到服务器。
如果需要发送表单的其他表单项,可以填写多个,以逗号隔开。
### 演示例子
~~~
class Index extends Admin
{
public function add()
{
// 使用ZBuilder构建表单页面,并将页面标题设置为“添加”
$list_province = ['gd' => '广东', 'gx' => '广西'];
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city,area')
->addLinkage('city', '选择城市', '', '', '', url('get_area'), 'area')
->addSelect('area', '选择地区')
->fetch();
}
// 根据省份获取城市
public function get_city($province = '')
{
$arr['code'] = '1'; //判断状态
$arr['msg'] = '请求成功'; //回传信息
$arr['list'] = [
['key' => 'gz', 'value' => '广州'],
['key' => 'sz', 'value' => '深圳'],
]; //数据
return json($arr);
}
// 根据城市获取地区
public function get_area($city = '')
{
$arr['code'] = '1'; //判断状态
$arr['msg'] = '请求成功'; //回传信息
$arr['list'] = [
['key' => 'th', 'value' => '天河'],
['key' => 'by', 'value' => '白云'],
]; //数据
return json($arr);
}
}
~~~
### 编辑页面
在编辑页面,普通联动的列表需要先查询出来,再赋值给各个下拉框,这样才能显示对应的值。
~~~
class Index extends Admin
{
public function edit($id)
{
// 获取编辑数据
$info = Db::name('...')->find();
// 查询省份列表,一般是去数据库查询,这里用固定数组代替
$list_province = ['gd' => '广东', 'gx' => '广西'];
// 这里需要根据已经选择的省份,查询数据库获取城市列表
$list_city = Db::name('city')->where('province', $info['province'])->column('id,name');
// 这里需要根据已经选择的城市,查询数据库获取地区列表
$list_area = Db::name('area')->where('city', $info['city'])->column('id,name');
return ZBuilder::make('form')
->addLinkage('province', '选择省份', '', $list_province, '', url('get_city'), 'city,area')
->addLinkage('city', '选择城市', '', $list_city , '', url('get_area'), 'area')
->addSelect('area', '选择地区', '', $list_area)
->setFormData($info)
->fetch();
}
}
~~~