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

• 支持输入、文本区域、选择、多选、复选框和单选元素组件。
• 支持 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 protonemedia/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视图和组件，否则不需要进一步配置。

用法

输入和textarea元素

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']" />

您还可以向 select 元素添加一个 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对input groups进行了简化。您可以根据需要以任何顺序添加任意数量的项目。使用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

变更日志

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

贡献

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

其他Laravel包

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

安全

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

鸣谢

• Pascal Baljet
• 所有贡献者

许可

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

实物商品

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