README

用于在 Laravel 中构建和渲染表单的库。

我们最初开发这个库是为了我们基于 Bootstrap 4 和 CoreUI 的内部系统，我们尽量不偏向于标记；然而，这个库确实考虑了 Bootstrap 4 的类来生成标记。

如果你没有使用 Bootstrap 4，或者使用的是旧版本，你需要添加兼容的 CSS 类来处理组件的样式。

这个库处于早期发布阶段，并且正在等待单元测试。

安装

composer require balfour/laravel-form-builder

创建表单

你可以通过构建一个 Form 来动态创建表单，或者创建一个自定义类，如 CreateUserForm，在类的构造函数中构建组件。

namespace App\Forms;

use App\Models\Role;
use Balfour\LaravelFormBuilder\Form;
use Balfour\LaravelFormBuilder\Components\Checkboxes;
use Balfour\LaravelFormBuilder\Components\EmailInput;
use Balfour\LaravelFormBuilder\Components\MobileNumberInput;
use Balfour\LaravelFormBuilder\Components\NumberInput;
use Balfour\LaravelFormBuilder\Components\PhoneNumberInput;
use Balfour\LaravelFormBuilder\Components\Row;
use Balfour\LaravelFormBuilder\Components\TextInput;

class CreateUserForm extends Form
{
    public function __construct()
    {
        $this->route('post.create_user')
            ->button('Create')
            ->with([
                TextInput::build()
                    ->name('first_name')
                    ->required(),
                TextInput::build()
                    ->name('last_name')
                    ->required(),
                EmailInput::build()
                    ->required()
                    ->rule('unique:users'),
                Row::build()
                    ->with([
                        MobileNumberInput::build()
                            ->rule('unique:users'),
                        PhoneNumberInput::build()
                            ->name('office_number')
                            ->rule('unique:users'),
                    ]),
                Row::build()
                    ->with([
                        NumberInput::build()
                            ->name('phone_extension')
                            ->rule('unique:users'),
                        TextInput::build()
                            ->name('skype')
                            ->rule('unique:users'),
                    ]),
                Checkboxes::build()
                    ->name('roles')
                    ->options(Role::class)
                    ->setVisibility(auth()->user()->can('assign-role')),
            ]);
    }
}

你可以在控制器中创建表单对象，并将其传递到视图中。

return view('create_user', ['form' => new CreateUserForm()])

在你的视图中，你可以调用表单的 render 方法。

<html>
<head>
    <title>Create User</title>
</head>
<body>
{!! $form->render !!}
</body>
</html>

填写表单

$form->fill() 方法可用于设置所有表单组件的默认值。

此方法可以接受一个 array 或 key=>value 对，或一个 model。

以下是一个示例 EditUserForm，它从一个现有的用户模型中填充。

namespace App\Forms;

use App\Models\Role;
use App\Models\User;
use Balfour\LaravelFormBuilder\Form;
use Balfour\LaravelFormBuilder\Components\Checkboxes;
use Balfour\LaravelFormBuilder\Components\EmailInput;
use Balfour\LaravelFormBuilder\Components\MobileNumberInput;
use Balfour\LaravelFormBuilder\Components\NumberInput;
use Balfour\LaravelFormBuilder\Components\PhoneNumberInput;
use Balfour\LaravelFormBuilder\Components\Row;
use Balfour\LaravelFormBuilder\Components\TextInput;
use Illuminate\Validation\Rule;

class EditUserForm extends Form
{
    public function __construct(User $user)
    {
        $this->route('post.edit_user', [$user])
            ->button('Save')
            ->with([
                TextInput::build()
                    ->name('first_name')
                    ->required(),
                TextInput::build()
                    ->name('last_name')
                    ->required(),
                EmailInput::build()
                    ->required()
                    ->disabled(),
                Row::build()
                    ->with([
                        MobileNumberInput::build()
                            ->rule(Rule::unique('users')->ignore($user)),
                        PhoneNumberInput::build()
                            ->name('office_number')
                            ->rule(Rule::unique('users')->ignore($user)),
                    ]),
                Row::build()
                    ->with([
                        NumberInput::build()
                            ->name('phone_extension')
                            ->rule(Rule::unique('users')->ignore($user)),
                        TextInput::build()
                            ->name('skype')
                            ->rule(Rule::unique('users')->ignore($user)),
                    ]),
                Checkboxes::build()
                    ->name('roles')
                    ->options(Role::class)
                    ->setVisibility(auth()->user()->can('assign-role'))
                    ->defaults(function () use ($user) {
                        return $user->roles
                            ->pluck('id')
                            ->toArray();
                    }),
                ToggleSwitch::build()
                    ->name('is_two_factor_auth_enforced')
                    ->label('2 Factor Authentication Enforced')
                    ->onLabel('Yes')
                    ->offLabel('No'),
                ToggleSwitch::build()
                    ->name('is_enabled')
                    ->label('Account Enabled')
                    ->onLabel('Yes')
                    ->offLabel('No'),
            ])->fill($user);
    }
}

当我们构建表单时，我们只需要传入一个用户模型，所有组件都将从模型中填充。

use App\Forms\EditUserForm;
use App\Models\User;

$user = User::find(3);
$form = new EditUserForm($user);

echo $form->render();

表单验证

库会自动为你根据表单嵌套的组件生成验证规则。你可以调用 $form->getValidationRules() 方法来生成规则。

实际表单数据的验证留给你自己处理。

控制器验证

use App\Forms\CreateUserForm;
use Illuminate\Foundation\Bus\DispatchesJobs;
use Illuminate\Foundation\Validation\ValidatesRequests;
use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
use Illuminate\Http\Request;
use Illuminate\Routing\Controller;

class UserController extends Controller
{
    public function postCreate(Request $request)
    {
        $request->validate((new CreateUserForm())->getValidationRules());
    }
}

表单请求验证

namespace App\Http\Requests;

use App\Forms\CreateUserForm;
use Illuminate\Foundation\Http\FormRequest;

class CreateUserRequest extends FormRequest
{
    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return (new CreateUserForm())->getValidationRules();
    }
}

组件

以下组件包含在此包中

复选框（单个）
复选框（多个）
日期输入
电子邮件输入
字段集
文件输入
隐藏输入
手机号码输入
数字输入
密码输入
电话号码输入
单选按钮组
富文本编辑器
行
选择
文本区域
文本输入
时间选择器
切换开关

你也可以通过实现 ComponentInterface 或扩展 ComponentInterface 的 FormControlInterface 来创建你自己的自定义组件。

复选框（单个）

use Balfour\LaravelFormBuilder\Components\Checkbox;

Checkbox::build()
    ->name('remember_me')
    ->label('Remember me for my next visit')
    ->defaults(1);
    
Checkbox::build()
    ->name('agree')
    ->label('I agree to the terms and conditions')
    ->rule('accepted');

复选框（多个）

use App\Models\Role;
use Balfour\LaravelFormBuilder\Components\Checkboxes;

$user = auth()->user();

// using an array of options
$roles = Role::pluck('name', 'id')
    ->toArray();

Checkboxes::build()
    ->name('roles')
    ->options($roles)
    ->defaults(function () use ($user) {
        return $user->roles
            ->pluck('id')
            ->toArray();
    });

// using a model, or options class
// the class must have a static listify() method which returns an array of key => value pairs
Checkboxes::build()
    ->name('roles')
    ->options(Role::class)
    ->setVisibility(auth()->user()->can('assign-role'))
    ->defaults(function () use ($user) {
        return $user->roles
            ->pluck('id')
            ->toArray();
    });
    
// using a callable to resolve options
Checkboxes::build()
    ->name('roles')
    ->options(function () {
        return Role::pluck('name', 'id')
            ->toArray();
    });

日期输入

use Balfour\LaravelFormBuilder\Components\DateInput;

// if no label is given, it's automagically generated from the component's name
DateInput::build()
    ->name('start_date');
   
// we can add a custom validation rule on top of the automagically generated ones
DateInput::build()
    ->name('start_date')
    ->rule('after:today');

电子邮件输入

use Balfour\LaravelFormBuilder\Components\EmailInput;

EmailInput::build()
    ->name('email');
    
// here's another custom validation rule on top of the 'email' one
EmailInput::build()
    ->name('email')
    ->rule('unique:users,email');

字段集

use Balfour\LaravelFormBuilder\Components\DateInput;
use Balfour\LaravelFormBuilder\Components\FieldSet;

FieldSet::build()
    ->legend('General')
    ->with([
        DateInput::build()
            ->name('start_date')
            ->required(),
        DateInput::build()
            ->name('end_date')
            ->required(),
    ]);

文件输入

use Balfour\LaravelFormBuilder\Components\FileInput;

FileInput::build()
    ->name('photo')
    ->required()
    ->mimes(['image/jpeg'])
    ->maxSize('5120')

隐藏输入

use Balfour\LaravelFormBuilder\Components\HiddenInput;

HiddenInput::build()
    ->name('user_id')
    ->defaults(1);

手机号码输入

use Balfour\LaravelFormBuilder\Components\MobileNumberInput;

MobileNumberInput::build()
    ->defaults(auth()->user()->mobile_number);

数字输入

use Balfour\LaravelFormBuilder\Components\NumberInput;

NumberInput::build()
    ->name('age');

密码输入

use Balfour\LaravelFormBuilder\Components\PasswordInput;

PasswordInput::build();

// if you want a custom label...
PasswordInput::build()
    ->name('Your Password');

电话号码输入

use Balfour\LaravelFormBuilder\Components\PhoneNumberInput;

PhoneNumberInput::build()
    ->defaults(auth()->user()->phone_number);

单选按钮组

use Balfour\LaravelFormBuilder\Components\RadioButtonGroup;

RadioButtonGroup::build()
    ->name('food_preference')
    ->options([
        [
            'key' => 'chicken',
            'value' => 'Chicken',
        ],
        [
            'key' => 'beef',
            'value' => 'Beef',
        ],
    ])
    ->defaults('chicken');
    
// you can also add icons
RadioButtonGroup::build()
    ->name('food_preference')
    ->options([
        [
            'key' => 'chicken',
            'value' => 'Chicken',
            'icon' => 'fas fa-egg',
        ],
        [
            'key' => 'beef',
            'value' => 'Beef',
            'icon' => 'fas fa-hamburger',
        ],
    ])
    ->defaults('chicken');

富文本编辑器

use Balfour\LaravelFormBuilder\Components\RichTextEditor;

// this will render a textarea with a 'wysiwyg' class
// it's up to you to instantiate a rich text editor on this element, such as with
// TinyMCE or Froala Editor
RichTextEditor::build()
    ->name('description')
    ->rows(10)
    ->required();

行

use Balfour\LaravelFormBuilder\Components\DateInput;
use Balfour\LaravelFormBuilder\Components\Row;

Row::build()
    ->with([
        DateInput::build()
            ->name('start_date')
            ->required(),
        DateInput::build()
            ->name('end_date')
            ->required(),
    ]);

选择

use App\Models\Country;
use Balfour\LaravelFormBuilder\Components\Select;

// using an array of options, and include a default 'empty' option
Select::build()
    ->name('country_id')
    ->options([
        1 => 'South Africa',
        2 => 'Amsterdam',
        3 => 'Italy',
    ])
    ->hasEmptyOption();

// using a model, or options class
// the class must have a static listify() method which returns an array of key => value pairs
Select::build()
    ->name('country_id')
    ->options(Country::class)
    ->defaults(1);
    
// using a callable to resolve options
Select::build()
    ->name('country_id')
    ->options(function () {
        return [
            1 => 'South Africa',
            2 => 'Amsterdam',
            3 => 'Italy',
        ];
    });

文本区域

use Balfour\LaravelFormBuilder\Components\TextArea;

TextArea::build()
    ->name('description')
    ->rows(15)
    ->required()
    ->defaults('This is the default description.');

文本输入

use Balfour\LaravelFormBuilder\Components\TextInput;

TextInput::build()
    ->name('first_name')
    ->required()
    ->defaults(auth()->user()->first_name);
    
// you can show a placeholder message
TextInput::build()
    ->name('first_name')
    ->required()
    ->placeholder('Your First Name')
    ->defaults(auth()->user()->first_name);

// you can also customise the type, and add a custom validation rule
TextInput::build()
    ->name('email')
    ->type('email')
    ->required()
    ->defaults(auth()->user()->email)
    ->rule('unique:users,email');

时间选择器

use Balfour\LaravelFormBuilder\Components\TimePicker;

// the component is rendered as an input with a 'time-picker' class
// you'd need to use a timepicker js lib of your choice to render it
TimePicker::build()
    ->name('start_time')
    ->required()
    ->defaults('14:30');

切换开关

use Balfour\LaravelFormBuilder\Components\ToggleSwitch;

ToggleSwitch::build()
    ->name('two_factor_authentication_enabled')
    ->defaults(true);
    
// use custom on and off labels
ToggleSwitch::build()
    ->name('subscribe')
    ->onLabel('Yes')
    ->offLabel('No')
    ->defaults(true);

balfour/laravel-form-builder

维护者

详细信息