表单基本使用
<h1>表单基本使用</h1>
<h2>示例</h2>
<p><code>Dcat\Admin\Form</code>类用于快速生成表单页面，先来个例子，数据库中有<code>movies</code>表</p>
<pre><code class="language-sql">CREATE TABLE `movies` (
`id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`title` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
`director` int(10) unsigned NOT NULL,
`describe` varchar(255) COLLATE utf8_unicode_ci NOT NULL,
`rate` tinyint unsigned NOT NULL,
`released` enum(0, 1),
`release_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
`created_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
`updated_at` timestamp NOT NULL DEFAULT '0000-00-00 00:00:00',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci;
</code></pre>
<p>对应的数据模型为<code>App\Models\Movie</code>，数据仓库为<code>App\Admin\Repositories\Movie</code>：</p>
<pre><code class="language-php">use App\Admin\Repositories\Movie;
use Dcat\Admin\Form;
use Dcat\Admin\Admin;
$form = Form::make(new Movie(), function (Form $form) {
// 显示记录id
$form-&gt;display('id', 'ID');
// 添加text类型的input框
$form-&gt;text('title', '电影标题');
$directors = [
1 =&gt; 'John',
2 =&gt; 'Smith',
3 =&gt; 'Kate',
];
$form-&gt;select('director', '导演')-&gt;options($directors);
// 添加describe的textarea输入框
$form-&gt;textarea('describe', '简介');
// 数字输入框
$form-&gt;number('rate', '打分');
// 添加开关操作
$form-&gt;switch('released', '发布？');
// 添加日期时间选择框
$form-&gt;datetime('release_at', '发布时间');
// 两个时间显示
$form-&gt;display('created_at', '创建时间');
$form-&gt;display('updated_at', '修改时间');
});</code></pre>
<h2>数据仓库</h2>
<p>数据仓库(<code>Repository</code>)是一个可以提供特定接口对数据进行读写操作的类，通过数据仓库的引入，可以让页面的构建不再关心数据读写功能的具体实现，开发者只需要实现特定的操作接口即可轻松切换数据源。关于数据仓库的详细用法请参考文档<a href="model-repository.md">数据仓库</a>。</p>
<h2>表单定义</h2>
<p>推荐使用以下方式构建表单</p>
<pre><code class="language-php">use App\Admin\Repositories\Movie;
use Dcat\Admin\Form;
use Dcat\Admin\Admin;
$form = Form::make(new Movie, function (Form $form) {
// 显示记录id
$form-&gt;display('id', 'ID');
$form-&gt;select('director', '导演')-&gt;options($directors);
...
});</code></pre>
<h3>获取当前模型数据</h3>
<p>在闭包内可以获取到当前模型的数据（编辑）</p>
<pre><code class="language-php">Form::make(new Movie, function (Form $form) {
// 显示记录id
$form-&gt;display('id', 'ID');
// 获取模型数据，如果&quot;status == 1&quot;则显示&quot;rate&quot;字段
if ($form-&gt;model()-&gt;status == 1) {
$form-&gt;number('rate');
}
$form-&gt;select('director', '导演')-&gt;options($directors);
...
});</code></pre>
<h2>自定义工具</h2>
<p>表单右上角默认有返回和跳转列表两个按钮工具, 可以使用下面的方式修改它:</p>
<pre><code class="language-php">$form-&gt;tools(function (Form\Tools $tools) {
// 去掉跳转列表按钮
$tools-&gt;disableList();
// 去掉跳转详情页按钮
$tools-&gt;disableView();
// 去掉删除按钮
$tools-&gt;disableDelete();
// 添加一个按钮, 参数可以是字符串, 匿名函数, 或者实现了Renderable或Htmlable接口的对象实例
$tools-&gt;append('&lt;a class=&quot;btn btn-sm btn-danger&quot;&gt;&lt;i class=&quot;fa fa-trash&quot;&gt;&lt;/i&gt;&amp;nbsp;&amp;nbsp;delete&lt;/a&gt;');
});
// 去除整个工具栏内容
$form-&gt;disableHeader();
// 也可以通过以下方式去除工具栏的默认按钮
$form-&gt;disableListButton();
$form-&gt;disableViewButton();
$form-&gt;disableDeleteButton();
</code></pre>
<h3>自定义复杂工具按钮</h3>
<p>请参考文档<a href="action-form.md">表单动作</a></p>
<h2>表单底部</h2>
<p>使用下面的方法去掉form底部的元素</p>
<pre><code class="language-php">$form-&gt;footer(function ($footer) {
// 去掉`重置`按钮
$footer-&gt;disableReset();
// 去掉`提交`按钮
$footer-&gt;disableSubmit();
// 去掉`查看`checkbox
$footer-&gt;disableViewCheck();
// 去掉`继续编辑`checkbox
$footer-&gt;disableEditingCheck();
// 去掉`继续创建`checkbox
$footer-&gt;disableCreatingCheck();
// 设置`查看`默认选中
$footer-&gt;defaultViewChecked();
// 设置`继续编辑`默认选中
$footer-&gt;defaultEditingChecked();
// 设置`继续创建`默认选中
$footer-&gt;defaultCreatingChecked();
});
// 去除整个底部内容
$form-&gt;disableFooter();
// 也可以通过以下方式去底部元素
$form-&gt;disableSubmitButton();
$form-&gt;disableResetButton();
$form-&gt;disableViewCheck();
$form-&gt;disableEditingCheck();
$form-&gt;disableCreatingCheck();
// 设置`查看`默认选中
$form-&gt;defaultViewChecked();
// 设置`继续编辑`默认选中
$form-&gt;defaultEditingChecked();
// 设置`继续创建`默认选中
$form-&gt;defaultCreatingChecked();</code></pre>
<p>自定义视图</p>
<pre><code class="language-php">$form-&gt;footer(function ($footer) {
$footer-&gt;view('...', [...]);
});</code></pre>
<h2>常用方法</h2>
<h3>表单布局</h3>
<p>请参考<a href="model-form-layout.md">表单布局</a></p>
<h3>返回字段验证出错信息 (responseValidationMessages)</h3>
<p>通过<code>responseValidationMessages</code>方法可以很方便的返回字段验证出错信息，而不需要使用<code>Laravel validation</code>功能。</p>
<p>普通使用</p>
<pre><code class="language-php">protected function form()
{
return Form::make(new Model(), function (Form $form) {
if (...) { // 验证逻辑
$form-&gt;responseValidationMessages('title', 'title格式错误');
// 如有多个错误信息，第二个参数可以传数组
$form-&gt;responseValidationMessages('content', ['content格式错误', 'content不能为空']);
}
});
}</code></pre>
<p>在事件中使用
> {tip} 此方法仅在<code>submitted</code>事件中可用</p>
<pre><code class="language-php">$form-&gt;submitted(function (Form $form) {
// 接收表单参数
$title = $form-&gt;title;
if (...) { // 验证逻辑
$form-&gt;responseValidationMessages('title', 'title格式错误');
// 如有多个错误信息，第二个参数可以传数组
$form-&gt;responseValidationMessages('content', ['content格式错误', 'content不能为空']);
}
});</code></pre>
<h3>移除提交按钮</h3>
<pre><code class="language-php">// 去掉提交按钮
$form-&gt;disableSubmitButton();
// 去掉重置按钮
$form-&gt;disableResetButton();</code></pre>
<h3>忽略掉不需要保存的字段 (ignore)</h3>
<pre><code class="language-php">$form-&gt;ignore(['column1', 'column2', 'column3']);
// 取消已忽略的字段
$form-&gt;removeIgnoredFields(['column1',]);</code></pre>
<h3>设置宽度 (width)</h3>
<p>此处的宽度值是一个<code>1-12</code>之间的数字，第一个参数为 <code>field</code> 的宽，第二个参数为 <code>label</code> 的宽可省略</p>
<pre><code class="language-php">$form-&gt;width(10, 2);</code></pre>
<h3>设置表单提交的action</h3>
<pre><code class="language-php">$form-&gt;action('auth/users');</code></pre>
<h3>判断是否是新增 (isCreating)</h3>
<p>新增页面和保存新增数据都可以用这个方法判断</p>
<pre><code class="language-php">if ($form-&gt;isCreating()) {
...
}</code></pre>
<h3>判断是否是编辑 (isEditing)</h3>
<p>编辑页面和保存编辑数据都可以用这个方法判断</p>
<pre><code class="language-php">if ($form-&gt;isEditing()) {
...
}</code></pre>
<h3>判断是否是删除 (isDeleting)</h3>
<pre><code class="language-php">if ($form-&gt;isDeleting()) {
...
}</code></pre>
<h3>获取ID (getKey)</h3>
<p>新增页面无效，必须在闭包里面使用</p>
<pre><code class="language-php">return Form::make(new User, function (Form $form) {
$id = $form-&gt;getKey();
...
});</code></pre>
<h3>获取编辑数据 (model)</h3>
<p>新增页面无效，必须在闭包里面使用</p>
<pre><code class="language-php">return Form::make(new User, function (Form $form) {
$username = $form-&gt;model()-&gt;xxx;
...
});</code></pre>
<h3>获取表单提交的数据 (input)</h3>
<pre><code class="language-php">$form-&gt;saving(function (Form $form) {
$username = $form-&gt;username;
// 等同于
$username = $form-&gt;input('username');
});</code></pre>
<h3>修改或删除表单提交的数据</h3>
<pre><code class="language-php">$form-&gt;saving(function (Form $form) {
// 修改
$form-&gt;input('username', 'Marry');
// 或
$form-&gt;username = 'Marry';
// 删除
$form-&gt;deleteInput('username');
});</code></pre>
<h3>获取最终保存的数据 (updates)</h3>
<p>此方法仅在<code>saved</code>回调有效。</p>
<pre><code class="language-php">$form-&gt;saved(function (Form $form) {
$data = $form-&gt;updates();
});</code></pre>
<p><a name="redirect"></a></p>
<h3>页面跳转 (redirect)</h3>
<p>跳转到指定页面，此方法仅在<a href="model-form-callback.md">表单回调</a>事件内可用</p>
<pre><code class="language-php">// 跳转并提示成功信息
$form-&gt;saved(function (Form $form) {
return $form-&gt;response()-&gt;success('保存成功')-&gt;redirect('auth/user');
});
// 跳转并提示错误信息
$form-&gt;saving(function (Form $form) {
return $form-&gt;response()-&gt;error('系统错误')-&gt;redirect('auth/user');
});</code></pre>
<p><a name="confirm"></a></p>
<h3>显示确认弹窗 (confirm)</h3>
<p>点击表单提交按钮时弹出确认弹窗，如果是在普通数据表单中</p>
<pre><code class="language-php">$form-&gt;confirm('您确定要提交表单吗？', 'content');</code></pre>
<h3>设置外层容器 (wrap)</h3>
<pre><code class="language-php"> // 更改表格外层容器
$form-&gt;wrap(function (Renderable $view) {
$tab = Tab::make();
$tab-&gt;add('示例', $view);
$tab-&gt;add('代码', $this-&gt;code(), true);
return $tab;
});</code></pre>
<p><a name="saving"></a></p>
<h3>修改待保存的表单输入值 (saving)</h3>
<p>通过<code>saving</code>方法可以更改待保存数据的格式。</p>
<pre><code class="language-php">use Dcat\Admin\Support\Helper;
$form-&gt;mutipleFile('files')-&gt;saving(function ($paths) {
$paths = Helper::array($paths);
// 获取数据库当前行的其他字段
$username = $this-&gt;username;
// 最终转化为json保存到数据库
return json_encode($paths);
});</code></pre>
<p><a name="customFormat"></a></p>
<h3>修改表单数据显示 (customFormat)</h3>
<p>通过<code>customFormat</code>方法可以改变从外部注入到表单的字段值。</p>
<p>如下例子中，<code>mutipleFile</code>字段要求待渲染的字段值为数组格式，我们可以通过<code>customFormat</code>方法把从数据库查出的字段值转化为<code>array</code>格式</p>
<pre><code class="language-php">use Dcat\Admin\Support\Helper;
$form-&gt;mutipleFile('files')-&gt;saving(function ($paths) {
$paths = Helper::array($paths);
return json_encode($paths);
})-&gt;customFormat(function ($paths) {
// 获取数据库当前行的其他字段
$username = $this-&gt;username;
// 转为数组
return Helper::array($paths);
});</code></pre>