批量操作表单项 formBatchItem

批量操作表单项用于声明一个批量操作表单中的列，通常只能作为批量操作表单（formBatch）或批量操作表单面板（formBatchPanel）的内部组件使用。

用法

简单使用

批量操作表单项的用法与表单组（formGroup）类似，下面为一个简单用法。

zin 声明

formBatchItem
(
    set::name('title'),
    set::required(true),
    set::label('Title')
);

生成的 HTML

<th class="form-batch-head" data-required="true" data-name="title">
  <span class="form-label form-batch-label" required>Title</span>
</th>
<td class="form-batch-control" data-name="title">
  <input class="form-control is-required" type="text" autocomplete="off" name="title" id="title" />
</td>

设置表单控件

默认情况下会使用文本框控件来渲染表单项，使用 control 属性可以指定具体的控件，允许使用控件名称或控件属性数组。该特性由表单控件（control）实现。下面为一个使用 select 控件的例子：

$modules = array();
$modules[] = array('text' => '/', 'value' => 0);
$modules[] = array('text' => '/Website', 'value' => 1);

formBatchItem
(
    set::name('module'),
    set::label('Module'),
    set::items($modules),
    set::control('select')
);

设置列宽

与数据表格不同，在批量编辑表单中会使用真实的 <table> 来进行布局，所有列宽设置通过 CSS 应用到 <th> 和 <td> 上。通过 width 属性来设置列宽，通过 支持 ZUI 列宽设置方式，可以包含如下值：

• '100px'：指定具体宽度，单位为 px。
• '1/3'：指定相对宽度，相对于父元素宽度的比例。
• 8：指定相对宽度，相当于 CSS 类 .w-8（32px）。
• 'auto'：自动填充剩余宽度。
• '50%'：使用百分比指定相对父级的宽度。

针对不同内容类型的列，推荐列宽设置如下：

列类型	宽度设置
无固定长度的短文本	'200px'
无固定长度的长文本	'240px'
有固定长度的短文本 ，例如人名、指派给	'136px'
有固定长度短长文本	'160px'
图标类，例如优先级	'92px'
数字输入类，例如时间、故事点	'76px'
日期选择器	'136px'
ID	'38px'
操作列（2个按钮宽度为 48px，按钮大小16px，按钮间距4px）	'60px'

下面为一个列宽设置的例子：

formBatchItem
(
    set::name('module'),
    set::width('1/3')
);
formBatchItem
(
    set::name('category'),
    set::width('100px')
);
formBatchItem
(
    set::name('title'),
    set::width('30%')
);
formBatchItem
(
    set::name('desc'),
    set::width(8)  // 相当于 CSS 类 .w-8（32px）
);

设置该列启用“同上”

在批量编辑表单中，有时希望该列提供 “同上” 按钮来方便的将该列的值设置为上一行的值，可以通过 ditto 属性来实现：

formBatchItem
(
    set::name('title'),
    set::ditto(true),         // 开启同上功能
    set::defaultDitto('off'), // 可设置 `ditto` 初始值为 'off'，默认为 'on'
    set::label('Title')
);

隐藏本列表单

通过 hidden 属性置为 true 可隐藏本列表单:

formBatchItem
(
    set::name('title'),
    set::ditto(true),
    set::label('Title'),
    set::hidden(true)
);

属性

名称	类型	可选	默认值	说明
name	string	—	—	表单项名称，无需包含 []。
label	stringbool	—	—	列标题。
labelClass	string	✓	null	列标题类名。
labelProps	string	✓	null	列标题属性，例如 array('data-toggle' => 'tooltip', 'data-title' => 'This is a tip')。
required	boolstring	✓	"auto"	是否必填，如果设置为 "auto"，则自动从当前模块 config 中查询。
control	arraystring	✓	null	控件类型或控件配置。
width	numberstring	✓	null	列宽度，如果设置为 "auto" 则自动填充剩余宽度。
minWidth	numberstring	✓	null	列最小宽度。
value	stringarray	✓	null	默认值。
disabled	bool	✓	null	是否禁用。
items	array	✓	null	选项，当控件类型为下拉菜单时使用此属性指定下拉菜单项。
placeholder	string	✓	null	占位文本。
tip	string	✓	null	显示在列标题上的提示文本。
tipClass	string	✓	null	列标题上的提示触发按钮类名。
tipIcon	string	✓	"info-sign"	列标题上的提示触发按钮图标。
tipProps	string	✓	null	列标题上的提示触发按钮其他属性。
ditto	bool	✓	null	是否显示同上按钮。
defaultDitto	string	✓	"on"	同上按钮的默认值。
hidden	bool	✓	false	是否隐藏。

参考

• 表单控件组 formGroup
• 表单控件组 control
• 批量操作表单 formBatch
• 批量操作表单面板 formBatchPanel