README

⚠️ 此包已弃用。它不支持 Livewire 3 和 Tailwind 3，且将不再维护。

Laravel 表单组件

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

赞助此包！

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

Laravel Splade

你听说过 Laravel Splade 吗？🤩

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

特性

📺 想要看这个包的实际应用？加入 11 月 19 日 14:00 CET 的直播： https://youtu.be/7eNZS4U7xyM

用于输入、textarea、选择、多选、复选框和单选元素的组件。
支持 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、10.0、11.0

安装

您可以通过 composer 安装此包

composer require coliving/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 中。

您可以通过向 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="ProtoneMedia\LaravelFormComponents\Support\ServiceProvider"

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

组件逻辑

您可以将自己的组件类绑定到任何元素。在form-components.php配置文件中，您可以按组件更改类。由于组件的逻辑相当复杂，强烈建议您从复制默认组件作为起点开始编辑。默认组件类位于vendor/protonemedia/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起，您可以通过向输入、选择（排除multiple）和文本区域添加floating属性来添加浮动标签。

<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

变更日志

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

贡献

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

其他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：此包为 Laravel 提供了 FFmpeg 的集成。文件的存储由 Laravel 的 Filesystem 处理。
Laravel Paddle：Paddle.com API 集成到 Laravel，支持 webhooks 事件。
Laravel Verify New Email：此包增加了对新电子邮件地址的验证支持：当用户更新其电子邮件地址时，新地址未经验证不会替换旧地址。
Laravel WebDAV：Laravel 文件系统的 WebDAV 驱动程序。

安全

如果您发现任何安全相关的问题，请发送电子邮件至 pascal@protone.media，而不是使用问题跟踪器。

鸣谢

许可

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

开源软件

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

coliving / laravel-form-components

维护者

详情