工具表单

工具表单(Dcat\Admin\Widgets\Form)用来构建表单和处理提交数据，可以很方便的独立处理数据，而不需要额外注册路由。

基本使用

用命令admin:form来生成表单类文件：

  1. php artisan admin:form Setting

将会生成表单文件app/Admin/Forms/Setting.php

  1. <?php
  3. namespace App\Admin\Forms;
  5. use Dcat\Admin\Widgets\Form;
  6. use Symfony\Component\HttpFoundation\Response;
  8. class Setting extends Form
  9. {
  10.     // 处理表单提交请求
  11.     public function handle(array $input)
  12.     {
  13.         // dump($input);
  15.         // return $this->error('Your error message.');
  17.         return $this->success('Processed successfully.', '/');
  18.     }
  20.     // 构建表单
  21.     public function form()
  22.     {
  23.         // Since v1.6.5 弹出确认弹窗 
  24.         $this->confirm('您确定要提交表单吗', 'content');
  26.         $this->text('name')->required();
  27.         $this->email('email')->rules('email');
  28.     }
  30.     /**
  31.      * 返回表单数据，如不需要可以删除此方法
  32.      *
  33.      * @return array
  34.      */
  35.     public function default()
  36.     {
  37.         return [
  38.             'name'  => 'John Doe',
  39.             'email' => 'John.Doe@gmail.com',
  40.         ];
  41.     }
  42. }

在上面的表单类里面，在form方法中构建表单项，使用方法和数据表单一致，default方法用来给这个表单项设置默认数据。

在页面中填入数据提交表单之后，请求会进入到handle方法中，在这里可以加入你的数据处理逻辑，处理完成之后可以通过success或error方法响应数据到前端：

  1.     public function handle(array $input)
  2.     {
  3.         // $input是你接收到的表单数据
  4.         // 在这里可以写你的处理逻辑
  7.         // 第一个参数是响应的成功信息，第二个参数是要跳转的路由
  8.         return $this->success('Processed successfully.', '/');
  9.     }

然后按照下面的方法将上面的表单放到你的页面中：

  1. <?php
  3. use App\Admin\Forms\Setting;
  4. use App\Http\Controllers\Controller;
  5. use Dcat\Admin\Widgets\Card;
  6. use Dcat\Admin\Layout\Content;
  8. class UserController extends Controller
  9. {
  10.     public function setting(Content $content)
  11.     {
  12.         return $content
  13.             ->title('网站设置')
  14.             ->body(new Card(new Setting()));
  15.     }
  16. }

弹出确认弹窗

{tip} Since v1.6.5

第二个参数可忽略

  1. $this->confirm('title', 'content');

响应方法

ajaxResponse 仅提示成功或失败信息，不跳转也不刷新页面

  1. public function handle(array $input)
  2. {
  3.     ...
  5.     return $this->ajaxResponse('操作失败', null, false);
  7.     return $this->ajaxResponse('操作成功');
  8. }

success 响应成功信息，第一个参数为提示信息，第二个参数为跳转地址，不传则刷新当前页

  1. public function handle(array $input)
  2. {
  3.     ...
  5.     return $this->success('操作成功');
  7.     return $this->success('操作成功', 'auth/users');
  8. }

error 响应事变信息，第一个参数为提示信息，第二个参数为跳转地址，不传则刷新当前页

  1. public function handle(array $input)
  2. {
  3.     ...
  5.     return $this->error('操作失败');
  7.     return $this->error('操作失败', 'auth/users');
  8. }

{tip} Since v1.6.0

location 刷新整个页面

  1. public function handle(array $input)
  2. {
  3.     ...
  5.     // 不传参数则刷新当前页面
  6.     return $this->location();
  8.     return $this->location('auth/user', '保存成功');
  10.     return $this->location('auth/user', [
  11.         'message' => '系统错误',
  12.         'status' => false,
  13.     ]);
  14. }

自定义表单保存的后续行为

{tip} Since 1.2.0

  1. <?php
  3. namespace App\Admin\Forms;
  5. use Dcat\Admin\Widgets\Form;
  6. use Symfony\Component\HttpFoundation\Response;
  8. class Setting extends Form
  9. {
  10.     ...
  12.     /**
  13.       * 设置表单保存成功后执行的JS
  14.       *
  15.       * v1.6.5 版本之前请用 buildSuccessScript 方法
  16.       * 
  17.      * @return string|void
  18.      */
  19.     protected function addSavedScript()
  20.     {
  21.         return <<<JS
  22.         // data 为接口返回数据
  23.         if (! data.status) {
  24.             Dcat.error(data.message);
  26.             return false;
  27.         }
  29.         Dcat.success(data.message);
  31.         if (data.redirect) {
  32.             Dcat.reload(data.redirect)
  33.         }
  35.         // 中止后续逻辑（默认逻辑）
  36.         return false;
  37. JS;
  38.     }
  40.     /**
  41.      * 设置表单保存失败后执行的JS
  42.       * 
  43.       * v1.6.5 版本之前请用 buildErrorScript 方法 
  44.      * 
  45.      * @return string|void
  46.      */
  47.     protected function addErrorScript()
  48.     {
  49.         return <<<JS
  50.         var errorData = JSON.parse(response.responseText);
  52.         if (errorData) {
  53.             Dcat.error(errorData.message);
  54.         } else {
  55.             console.log('提交出错', response.responseText);
  56.         }
  58.         // 终止后续逻辑执行（默认逻辑）
  59.         return false;
  60. JS;
  61.     }
  62. }

取消表单的Ajax提交

默认表单提交都使用Ajax进行提交,通过注入的 Form.js 进行流程控制. 如果需要原生表单行为,可以禁用此特

  1. $form->disableAjaxSubmit();

布局

{tip} Since v1.6.0

column多列布局

  1. <?php
  3. use Dcat\Admin\Widgets\Form;
  5. class Setting extends Form
  6. {
  7.     public function form()
  8.     {
  9.         $this->column(6, function () {
  10.             $this->text('text1');
  12.             ...
  13.         });
  15.         $this->column(6, function () {
  16.             $this->text('text2');
  18.             ...
  19.         });
  20.     }    
  21. }

tab选项卡布局

  1. <?php
  3. use Dcat\Admin\Widgets\Form;
  5. class Setting extends Form
  6. {
  7.     public function form()
  8.     {
  9.         $this->tab('选项卡1', function () {
  10.             $this->text('text1');
  12.             ...
  13.         });
  15.         $this->tab('选项卡2', function () {
  16.             $this->text('text2');
  18.             ...
  19.         });
  20.     }    
  21. }

row多行布局

  1. public function form()
  2. {
  3.     $this->row(function ($row) {
  4.         $row->width(3)->text('text1');
  6.         ...
  7.     });
  9.     $this->row(function ($row) {
  10.         $row->width(3)->text('text2');
  12.         ...
  13.     });
  14. }

在弹窗中显示

{tip} Since v1.7.0

基本用法

使用命令生成工具表单php artisan admin:form ResetPassword，然后修改表单文件如下

  1. <?php
  3. namespace App\Admin\Forms;
  5. use Dcat\Admin\Widgets\Form;
  7. class ResetPassword extends Form
  8. {
  9.     // 处理请求
  10.     public function handle(array $input)
  11.     {
  12.         $password = $input['password'] ?? null;
  14.         // 逻辑操作
  16.         return $this->success('密码修改成功');
  17.     }
  19.     public function form()
  20.     {
  21.         $this->password('password')->required();
  22.         // 密码确认表单
  23.         $this->password('password_confirm')->same('password');
  24.     }
  26.     // 返回表单数据，如不需要可以删除此方法
  27.     public function default()
  28.     {
  29.         return [
  30.             'password'         => '',
  31.             'password_confirm' => '',
  32.         ];
  33.     }
  34. }

使用

  1. use App\Admin\Forms\ResetPassword;
  2. use Dcat\Admin\Widgets\Modal;
  4. $modal = Modal::make()
  5.     ->lg()
  6.     ->title('修改密码')
  7.     ->body(ResetPassword::make())
  8.     ->button('修改密码');

异步加载

只需要让Form表单类实现Dcat\Admin\Contracts\LazyRenderable接口即可支持异步渲染功能，修改上面创建的工具表单类如下

  1. <?php
  3. namespace App\Admin\Forms;
  5. use Dcat\Admin\Widgets\Form;
  6. use Dcat\Admin\Traits\LazyWidget;
  7. use Dcat\Admin\Contracts\LazyRenderable;
  9. class ResetPassword extends Form implements LazyRenderable
  10. {
  11.     use LazyWidget; 
  13.     // 处理请求
  14.     public function handle(array $input)
  15.     {
  16.         // 获取外部传递参数
  17.         $id = $this->payload['id'] ?? null;
  19.         $password = $input['password'] ?? null;
  21.         // 逻辑操作
  23.         return $this->success('密码修改成功');
  24.     }
  26.     public function form()
  27.     {
  28.         // 获取外部传递参数
  29.         $id = $this->payload['id'] ?? null;
  31.         $this->password('password')->required();
  32.         // 密码确认表单
  33.         $this->password('password_confirm')->same('password');
  34.     }
  36.     // 返回表单数据，如不需要可以删除此方法
  37.     public function default()
  38.     {
  39.         // 获取外部传递参数
  40.         $id = $this->payload['id'] ?? null;
  42.         return [
  43.             'password'         => '',
  44.             'password_confirm' => '',
  45.         ];
  46.     }
  47. }

使用代码与上面基本一致，并且我们可以用payload方法往表单里面传递自定义参数

  1. use App\Admin\Forms\ResetPassword;
  2. use Dcat\Admin\Widgets\Modal;
  4. $modal = Modal::make()
  5.     ->lg()
  6.     ->title('修改密码')
  7.     ->body(ResetPassword::make()->payload(['id' => '...'])) // 传递自定义参数
  8.     ->button('修改密码');

表格行操作弹窗

{tip} Since v1.7.0

下面通过一个数据表格修改密码的行操作功能来展示弹窗结合工具表单的用法：

使用命令生成工具表单php artisan admin:form ResetPassword，然后修改表单文件如下

  1. <?php
  3. namespace App\Admin\Forms;
  5. use Dcat\Admin\Models\Administrator;
  6. use Dcat\Admin\Traits\LazyWidget;
  7. use Dcat\Admin\Widgets\Form;
  8. use Dcat\Admin\Contracts\LazyRenderable;
  10. class ResetPassword extends Form implements LazyRenderable
  11. {
  12.     use LazyWidget; // 使用异步加载功能
  14.     // 处理请求
  15.     public function handle(array $input)
  16.     {
  17.         // 获取外部传递参数
  18.         $id = $this->payload['id'] ?? null;
  20.         // 表单参数
  21.         $password = $input['password'] ?? null;
  23.         if (! $id) {
  24.             return $this->error('参数错误');
  25.         }
  27.         $user = Administrator::query()->find($id);
  29.         if (! $user) {
  30.             return $this->error('用户不存在');
  31.         }
  33.         $user->update(['password' => bcrypt($password)]);
  35.         return $this->success('密码修改成功');
  36.     }
  38.     public function form()
  39.     {
  40.         // 获取外部传递参数
  41.         //$id = $this->payload['id'] ?? null;
  43.         $this->password('password')->required();
  44.         // 密码确认表单
  45.         $this->password('password_confirm')->same('password');
  46.     }
  48.     // 返回表单数据，如不需要可以删除此方法
  49.     public function default()
  50.     {
  51.         return [
  52.             'password'         => '',
  53.             'password_confirm' => '',
  54.         ];
  55.     }
  56. }

然后运行php artisan admin:action命令，选择选项2，生成数据表格行操作类，并修改如下：

  1. <?php
  3. namespace App\Admin\Actions\Grid;
  5. use App\Admin\Forms\ResetPassword as ResetPasswordForm;
  6. use Dcat\Admin\Widgets\Modal;
  7. use Dcat\Admin\Grid\RowAction;
  9. class ResetPassword extends RowAction
  10. {
  11.     protected $title = '修改密码';
  13.     public function render()
  14.     {
  15.         // 实例化表单类并传递自定义参数
  16.         $form = ResetPasswordForm::make()->payload(['id' => $this->getKey()]);
  18.         return Modal::make()
  19.             ->lg()
  20.             ->title($this->title)
  21.             ->body($form)
  22.             ->button($this->title);
  23.     }
  24. }

使用

  1. use App\Admin\Actions\Grid\ResetPassword;
  3. $grid->actions([new ResetPassword()]);

效果

工具表单 - 图1

表格批量操作弹窗

{tip} Since v1.7.0

如果你想在批量操作按钮中使用表单弹窗，可以参考以下例子：

这里我们仍然沿用上面用到的App\Admin\Forms\ResetPassword表单，并修改如下

  1. <?php
  3. namespace App\Admin\Forms;
  5. use Dcat\Admin\Models\Administrator;
  6. use Dcat\Admin\Widgets\Form;
  7. use Dcat\Admin\Traits\LazyWidget;
  8. use Dcat\Admin\Contracts\LazyRenderable;
  10. class ResetPassword extends Form implements LazyRenderable
  11. {
  12.     use LazyWidget;
  14.     // 处理请求
  15.     public function handle(array $input)
  16.     {
  17.         // id转化为数组
  18.         $id = explode(',', $input['id'] ?? null);
  19.         $password = $input['password'] ?? null;
  21.         if (! $id) {
  22.             return $this->error('参数错误');
  23.         }
  25.         $users = Administrator::query()->find($id);
  27.         if ($users->isEmpty()) {
  28.             return $this->error('用户不存在');
  29.         }
  31.         // 这里改为循环批量修改
  32.         $users->each(function ($user) use ($password) {
  33.              $user->update(['password' => bcrypt($password)]);
  34.         });
  36.         return $this->success('密码修改成功');
  37.     }
  39.     public function form()
  40.     {
  41.         $this->password('password')->required();
  42.         // 密码确认表单
  43.         $this->password('password_confirm')->same('password');
  45.         // 设置隐藏表单，传递用户id
  46.         $this->hidden('id')->attribute('id', 'reset-password-id');
  47.     }
  49.     // 返回表单数据，如不需要可以删除此方法
  50.     public function default()
  51.     {
  52.         return [
  53.             'password'         => '',
  54.             'password_confirm' => '',
  55.         ];
  56.     }
  57. }

然后运行php artisan admin:action命令，选择选项1，生成数据表格批量操作类，并修改如下：

  1. <?php
  3. namespace App\Admin\Actions\Grid;
  5. use App\Admin\Forms\ResetPassword as ResetPasswordForm;
  6. use Dcat\Admin\Widgets\Modal;
  7. use Dcat\Admin\Grid\BatchAction;
  9. class BatchResetPassword extends BatchAction
  10. {
  11.     protected $title = '修改密码';
  13.     public function render()
  14.     {
  15.         // 实例化表单类
  16.         $form = ResetPasswordForm::make();
  18.         return Modal::make()
  19.             ->lg()
  20.             ->title($this->title)
  21.             ->body($form)
  22.             // 因为此处使用了表单异步加载功能，所以一定要用 onLoad 方法
  23.             // 如果是非异步方式加载表单，则需要改成 onShow 方法
  24.             ->onLoad($this->getModalScript())
  25.             ->button($this->title);
  26.     }
  28.     protected function getModalScript()
  29.     {
  30.         // 弹窗显示后往隐藏的id表单中写入批量选中的行ID
  31.         return <<<JS
  32. // 获取选中的ID数组
  33. var key = {$this->getSelectedKeysScript()}
  35. $('#reset-password-id').val(key);
  36. JS;
  37.     }
  38. }

使用

  1. use App\Admin\Actions\Grid\BatchResetPassword;
  3. $grid->batchActions([new BatchResetPassword()]);