README

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

赞助此包！

❤️ 我们自豪地通过开发和免费提供 Laravel 包来支持社区。如果此包为您节省了时间，或者您在专业上依赖它，请考虑 赞助维护和开发。跟踪问题和拉取请求需要时间，但我们很乐意提供帮助！

Laravel Splade

您听说过 Laravel Splade 吗？🤩

它是 Inertia.js 的 魔法 与 Blade 的 简单性 的结合。 Splade 提供了一种超级简单的方式来使用 Blade 模板构建单页应用程序。除了那种神奇的 SPA 感觉外，它还附带十多个组件来使您的应用程序闪闪发光并使其交互式，而无需离开 Blade。

功能

📺 想要看到此包的实际操作吗？加入 11 月 19 日 14:00 CET 的现场直播： https://youtu.be/7eNZS4U7xyM

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

要求

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

安装

您可以通过 composer 安装此包

composer require rahulabs/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堆栈，您可能希望将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而不是标签，当然您也可以更改元素的类型。

<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>

如果您需要一个可以选择多个选项的 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 关系的 support。要利用此功能，您必须向选择元素添加 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 组件的 show-errors 属性默认为 true。

<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 中。

您可以通过向 form-group 元素添加 inline 属性来在同一水平行中分组复选框和单选按钮。

<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="rahulabs\LaravelFormComponents\Support\ServiceProvider"

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

组件逻辑

您可以将自己的组件类绑定到任何元素。在 form-components.php 配置文件中，您可以更改每个组件的类。由于组件的逻辑相当复杂，强烈建议从默认组件复制作为起点开始编辑。您可以在 vendor/rahulabs/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

变更日志

有关最近更改的更多信息，请参阅CHANGELOG。

贡献

有关详细信息，请参阅CONTRIBUTING。

其他Laravel包

• Laravel Analytics Event Tracking ：一个Laravel包，可以轻松地将事件发送到Google Analytics。
• Laravel Blade On Demand ：一个Laravel包，可以在内存中编译Blade模板。
• Laravel Cross Eloquent Search ：一个Laravel包，可以在多个Eloquent模型中进行搜索。
• Laravel Eloquent Scope as Select ：停止在PHP中重复Eloquent查询范围和约束。此包允许您通过添加子查询来重复使用查询范围和约束。
• Laravel Eloquent Where Not ：此Laravel包允许您翻转/反转Eloquent范围，或任何查询约束。
• Laravel FFMpeg ：此包提供了FFmpeg与Laravel的集成。文件存储由Laravel的文件系统处理。
• Laravel Paddle ：支持webhooks/events的Paddle.com API集成Laravel。
• Laravel Verify New Email ：此包添加了对验证新电子邮件地址的支持：当用户更新其电子邮件地址时，在新的地址被验证之前，不会替换旧的地址。
• Laravel WebDAV ：Laravel文件系统的WebDAV驱动程序。

安全性

如果您发现任何与安全相关的问题，请通过电子邮件 pascal@protone.media 联系我们，而不是使用问题跟踪器。

致谢

• Pascal Baljet
• 所有贡献者

许可证

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

Treeware

此包是Treeware。如果您在生产中使用它，那么我们要求您为世界买一棵树，以感谢我们的工作。通过为Treeware森林做出贡献，您将为当地家庭创造就业机会并恢复野生动物栖息地。