README

一套Blade组件，用于快速构建带有Tailwind CSS v1、Tailwind CSS v2和Bootstrap 4的表单。支持验证、模型绑定、默认值、多语言支持，包含默认供应商样式，并可完全自定义！

... 👀 此包正在开发Pro版本：请查看formcomponents.pro！

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

功能

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

要求

PHP 7.4 + Laravel 7.0及以上版本

支持

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

安装

您可以通过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始终具有强烈的意见和限制。Blade Components很棒，因为额外的属性会被传递到元素中。这就是我们为什么喜欢使用组件来编写表单而不是使用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设置来切换框架。使用artisan vendor:publish命令发布配置文件。

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。

绑定目标到多个元素

您还可以通过使用@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属性而不是name属性。

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

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

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

选择元素

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

使用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 组件有一个 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="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 4

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

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

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

输入前缀和后缀

除了Tailwind功能之外，还支持输入组。使用 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>

帮助文本

您可以通过使用 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，而不是使用问题跟踪器。

致谢

许可

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

Treeware

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

feadbox / laravel-form-components

维护者

详细信息