README

一组 Blade 组件，用于快速使用 Tailwind CSS v1、Tailwind CSS v2、Bootstrap 4 和 Bootstrap 5 构建表单。支持验证、模型绑定、默认值、翻译，包含默认供应商样式和完全可定制！

特性

支持输入、文本区域、选择框、多选框、复选框和单选框等元素组件。
支持 Tailwind v1，并使用 Tailwind CSS Custom Forms。
支持 Tailwind v2，并使用 Tailwind Forms。
支持 Bootstrap 4 表单。
支持 Bootstrap 5 表单。
组件逻辑与 Blade 视图独立，Tailwind 和 Bootstrap 视图使用相同的逻辑。
将目标绑定到表单（或一组元素）以提供默认值（模型绑定）。
支持 Laravel Livewire v2。
支持 Spatie 的 laravel-translatable。
使用旧输入重新填充表单。
验证错误。
表单方法欺骗。.
组件类和 Blade 视图完全可定制。
支持为组件添加前缀。

需求

PHP 8.0 或更高版本
Laravel 9.0 或更高版本

安装

您可以通过 composer 安装此包

composer require diviky/laravel-form-components

如果您正在使用 Tailwind，请确保已安装并配置了正确的插件（v1 或 v2）。

快速示例

<x-form>
    @bind($user)
        <x-form-input name="last_name" label="Last Name" />
        <x-form-select name="country_code" :options="$options" />
        <x-form-select name="interests[]" :options="$multiOptions" label="Select your interests" multiple />

        <!-- \Spatie\Translatable\HasTranslations -->
        <x-form-textarea name="biography" language="nl" placeholder="Dutch Biography" />
        <x-form-textarea name="biography" language="en" placeholder="English Biography" />

        <!-- Inline radio inputs -->
        <x-form-group name="newsletter_frequency" label="Newsletter frequency" inline>
            <x-form-radio name="newsletter_frequency" value="daily" label="Daily" />
            <x-form-radio name="newsletter_frequency" value="weekly" label="Weekly" />
        </x-form-group>

        <x-form-group>
            <x-form-checkbox name="subscribe_to_newsletter" label="Subscribe to newsletter" />
            <x-form-checkbox name="agree_terms" label="Agree with terms" />
        </x-form-group>

        <x-form-submit />
    @endbind
</x-form>

前言

乍一看，使用 PHP 生成 HTML 表单看起来很棒。PHP 的强大功能可以使它不那么冗余，并且直接从您的 PHP 代码中解决输入值和验证状态是非常好的。然而，当表单变得更加复杂时，保持您的 PHP 代码整洁和有序就变得更加困难。通常，您会结束于编写大量自定义代码，编写扩展和覆盖默认值，只是为了在表单中添加一些小功能。

经过多年的尝试，感觉直接在 HTML 中编写大多数表单是最通用的解决方案。您可以添加辅助文本、图标、工具提示、弹出窗口、自定义部分和 JavaScript 集成，无论何时何地，都可以按照您喜欢的方式添加。Laravel Blade 组件的强大功能使我们能够在不将整个表单构建过程引入 PHP 的情况下添加各种功能。

让我们看看这个x-form示例。action属性是可选的，但您可以使用简单的HTML属性将硬编码的基本值传递给组件。同样，您可以使用:前缀将PHP表达式和变量传递给属性。您需要Alpine.js或VueJS指令吗？没问题！

<x-form action="/api/user">
    <!-- ... -->
</x-form>

<x-form :action="route('api.user.store')" v-on:submit="checkForm">
    <!-- ... -->
</x-form>

配置

您可以通过更新form-components.php配置文件中的framework设置来切换框架。查看发布配置和视图文件的自定义部分。如果您使用的是Laravel Jetstream的Livewire Stack，您可能希望将framework配置键设置为tailwind-forms-simple。

return [
    'framework' => 'bootstrap-4',
];

除非您想自定义Blade视图和组件，否则不需要进一步配置。

使用

输入和文本区域元素

input或textarea的最小要求是name属性。

<x-form-input name="company_name" />

您可以添加一个label属性，它也可以被计算。

<x-form-input name="company_name" label="Company name" />
<x-form-input name="company_name" :label="trans('forms.company_name')" />

您还可以选择使用placeholder而不是标签，当然您也可以更改元素的type。

<x-form-input type="email" name="current_email" placeholder="Current email address" />

默认情况下，每个元素都会显示验证错误，但您可以选择隐藏它们。

<x-form-textarea name="description" :show-errors="false" />

默认值和绑定

您可以使用default属性来指定元素的默认值。

<x-form-textarea name="motivation" default="I want to use this package because..." />

绑定目标

除了设置默认值外，您还可以传递一个目标，如Eloquent模型。现在组件将根据name从目标获取值。

<x-form-textarea name="description" :bind="$video" />

在上面的例子中，其中$video是一个Eloquent模型，默认值将是$video->description。

日期转换

如果您使用Eloquent的日期转换功能，您可以通过将use_eloquent_date_casting配置键设置为true来使用表单中的日期属性。出于兼容性原因，此功能默认是禁用的。

return [
    'use_eloquent_date_casting' => true,
];

您可以在Eloquent模型中使用dates属性或casts属性来指定日期属性

class ActivityModel extends Model
{
    public $dates = ['finished_at'];

    public $casts = [
        'started_at'   => 'date',
        'failed_at'    => 'datetime',
        'completed_at' => 'date:d-m-Y',
        'skipped_at'   => 'datetime:Y-m-d H:i',
    ];
}

<x-form-input name="completed_at" :bind="$activity" />

在上面的例子中，默认值将被格式化为31-10-2021。

将目标绑定到多个元素

您还可以使用@bind指令绑定目标。这将绑定目标到直到@endbind指令的所有元素。

<x-form>
    @bind($video)
        <x-form-input name="title" label="Title" />
        <x-form-textarea name="description" label="Description" />
    @endbind
</x-form>

您甚至可以混合目标！

<x-form>
    @bind($user)
        <x-form-input name="full_name" label="Full name" />

        @bind($userProfile)
            <x-form-textarea name="biography" label="Biography" />
        @endbind

        <x-form-input name="email" label="Email address" />
    @endbind
</x-form>

覆盖或删除绑定

您可以通过使用:bind属性将目标直接传递给元素来覆盖@bind指令。如果您想为特定元素删除绑定，请传递false。

<x-form>
    @bind($video)
        <x-form-input name="title" label="Title" />
        <x-form-input :bind="$videoDetails" name="subtitle" label="Subtitle" />
        <x-form-textarea :bind="false" name="description" label="Description" />
    @endbind
</x-form>

Laravel Livewire

您可以使用@wire和@endwire指令将表单绑定到Livewire组件。让我们看看官方Livewire文档中的ContactForm示例。

use Livewire\Component;

class ContactForm extends Component
{
    public $name;
    public $email;

    public function submit()
    {
        $this->validate([
            'name' => 'required|min:6',
            'email' => 'required|email',
        ]);

        Contact::create([
            'name' => $this->name,
            'email' => $this->email,
        ]);
    }

    public function render()
    {
        return view('livewire.contact-form');
    }
}

通常您会使用wire:model属性来将组件属性与表单元素绑定。通过使用@wire指令，此包将自动添加wire:model属性。

<x-form wire:submit.prevent="submit">
    @wire
        <x-form-input name="name" />
        <x-form-input name="email" />
    @endwire

    <x-form-submit>Save Contact</x-form-submit>
</x-form>

此外，您还可以将一个可选的修饰符传递给@wire指令。此功能是在v2.4.0中添加的。如果您是从先前版本升级并且发布了Blade视图，您应该重新发布它们或手动更新它们。

<x-form wire:submit.prevent="submit">
    @wire('debounce.500ms')
        <x-form-input name="email" />
    @endwire
</x-form>

默认情况下，也可以使用 wire:model 属性。您可以将 default_wire 配置设置设置为 true 或类似 debounce.500ms 的修饰符。这样，您就不需要在视图中使用 @wire 和 @endwire 指令。您仍然可以使用 @wire 指令或手动将 wire:model 属性添加到表单元素中，来覆盖默认设置。

选择元素

除了 name 属性外，select 元素还有一个必需的 options 属性，它应该是一个简单的键值数组。

$countries = [
    'be' => 'Belgium',
    'nl' => 'The Netherlands',
];

<x-form-select name="country_code" :options="$countries" />

您还可以为 select 元素提供一个插槽。

<x-form-select name="country_code">
   <option value="be">Belgium</option>
   <option value="nl">The Netherlands</option>
</x-form-select>

如果您想有一个可以选择多个选项的选择元素，请将 multiple 属性添加到该元素。如果指定默认值，请确保它是一个数组。这也适用于绑定目标。

<x-form-select name="country_code[]" :options="$countries" multiple :default="['be', 'nl']" />

您可以为选择元素添加一个 placeholder 属性。这将预先添加一个禁用选项。

该功能自 v3.2.0 版本开始添加。如果您是从旧版本升级并且已发布 Blade 视图，您应该重新发布它们或手动更新它们。

<x-form-select name="country_code" placeholder="Choose..." />

渲染的 HTML

<select>
    <option value="" disabled>Choose...</option>
    <!-- other options... -->
</select>

使用 Eloquent 关系

此包内置了对 BelongsToMany、MorphMany 和 MorphToMany 关系的支援。要使用此功能，您必须将 multiple 和 many-relation 属性添加到选择元素。

在下面的示例中，您可以为绑定的视频添加一个或多个标签。通过使用 many-relation 属性，它将正确地从数据库中检索所选选项（附加的标签）。

<x-form>
    @bind($video)
        <x-form-select name="tags[]" :options="$tags" multiple many-relation />
    @endbind
</x-form>

复选框元素

复选框的默认值为 1，但您也可以自定义它。

<x-form-checkbox name="subscribe_to_newsletter" label="Subscribe to newsletter" />

如果您有一个复选框的字段集，您可以使用 form-group 组件将它们分组在一起。此组件具有可选的 label 属性，您还可以设置 name。这是一个处理数组验证的好方法。如果您禁用了单个复选框的错误，它将只显示一次验证错误。form-group 组件有一个默认为 true 的 show-errors 属性。

<x-form-group name="interests" label="Pick one or more interests">
    <x-form-checkbox name="interests[]" :show-errors="false" value="laravel" label="Laravel" />
    <x-form-checkbox name="interests[]" :show-errors="false" value="tailwindcss" label="Tailwind CSS" />
</x-form-group>

单选按钮元素

单选按钮的行为与复选框完全相同，只是 show-errors 属性默认为 false，因为您几乎总是希望将多个单选按钮包裹在 form-group 中。

您可以通过将 inline 属性添加到 form-group 元素，在同一水平行中对齐复选框和单选按钮。

<x-form-group name="notification_channel" label="How do you want to receive your notifications?" inline>
    <x-form-radio name="notification_channel" value="mail" label="Mail" />
    <x-form-radio name="notification_channel" value="slack" label="Slack" />
</x-form-group>

当您不使用目标绑定时，您可以使用 default 属性将单选按钮标记为选中。

<x-form-group name="notification_channel" label="How do you want to receive your notifications?">
    <x-form-radio name="notification_channel" value="mail" label="Mail" default />
    <x-form-radio name="notification_channel" value="slack" label="Slack" />
</x-form-group>

旧输入数据

当发生验证错误并且 Laravel 将您重定向回页面时，表单将使用旧输入数据重新填充。这些旧数据将覆盖任何绑定或默认值。

处理翻译

此包默认支持 spatie/laravel-translatable。您可以为您的元素添加一个 language 属性。

<x-form-input name="title" language="en" :bind="$book" />

这将生成以下 HTML

<input name="title[en]" value="Laravel: Up & Running" />

要从会话中获取验证错误，输入的名称将被映射到类似 title.en 的点表示法。旧输入数据也是这样处理的。

自定义 blade 视图

使用以下命令发布配置文件和 blade 视图

php artisan vendor:publish --provider="Diviky\LaravelFormComponents\Support\ServiceProvider"

您可以在 resources/views/vendor/form-components 文件夹中找到 blade 视图。可选地，在 form-components.php 配置文件中，您可以按组件更改 blade 视图的位置。

组件逻辑

您可以将自己的组件类绑定到任何元素。在 form-components.php 配置文件中，您可以按组件更改类。由于组件的逻辑相当复杂，强烈建议您将默认组件作为起点进行复制并开始编辑。您可以在 vendor/diviky/laravel-form-components/src/Components 文件夹中找到默认组件类。

组件前缀

您可以在 form-components.php 配置文件中定义一个前缀。

return [
    'prefix' => 'tailwind',
];

现在所有组件都可以这样引用

<x-tailwind-form>
    <x-tailwind-form-input name="company_name" />
</x-tailwind-form>

错误信息

默认情况下，错误信息位于元素下方。为了显示这些信息，我们创建了一个 FormErrors 组件。您也可以手动使用此组件。该元素接受一个可选的 bag 属性来指定 ErrorBag，默认为 default。

<x-form>
    <x-form-input name="company_name" :show-errors="false" />

    <!-- other elements -->

    <x-form-errors name="company_name" />

    <x-form-errors name="company_name" bag="register" />
</x-form>

提交按钮

标签默认为提交，但您可以使用插槽提供自己的内容。

<x-form-submit>
    <span class="text-green-500">Send</span>
</x-form-submit>

Bootstrap

您可以通过更新 form-components.php 配置文件中的 framework 设置来切换到 Bootstrap 4 或 Bootstrap 5。

return [
    'framework' => 'bootstrap-5',
];

在 form.blade.php 视图中添加了一些样式，以支持内联表单组。如果您想修改或删除它，请发布资源并更新视图文件。

Bootstrap 5 在表单方面有很多改变。如果您从 4 迁移到 5，请确保阅读有关表单的迁移日志。

输入组 / 前缀和后缀

除了 Tailwind 功能外，Bootstrap 4 还支持输入组。使用 prepend 和 append 插槽提供内容。

<x-form-input name="username" label="Username">
    @slot('prepend')
        <span>@</span>
    @endslot
</x-form-input>

<x-form-input name="subdomain" label="Subdomain">
    @slot('append')
        <span>.protone.media</span>
    @endslot
</x-form-input>

Bootstrap 5 中，输入组被简化了。您可以按任何顺序添加您想要的任何数量项目。使用 form-input-group-text 组件添加文本或复选框。

<x-form-input-group label="Profile" >
    <x-form-input name="name" placeholder="Name" id="name" />
    <x-form-input-group-text>@</x-form-input-group-text>
    <x-form-input name="nickname" placeholder="Nickname" id="nickname" />
    <x-form-submit />
</x-form-input-group>

浮动标签

自 Bootstrap 5 以来，您可以通过将 floating 属性添加到输入、选择（不包括 multiple）和文本区域来添加浮动标签。

<x-form-input label="Floating Label" name="float_me" id="float_me" floating />

帮助文本

您可以使用 help 插槽将块级帮助文本添加到任何元素。

<x-form-input name="username" label="Username">
    @slot('help')
        <small class="form-text text-muted">
            Your username must be 8-20 characters long.
        </small>
    @endslot
</x-form-input>

测试

composer test

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献指南。

许可

MIT 许可证（MIT）。有关更多信息，请参阅许可文件。

diviky / laravel-form-components

维护者

详情