README

该项目是基于 okipa/laravel-form-components 的维护分支。

节省时间，充分利用动态、现成和完全可定制的表单组件。

组件可以与以下 UI 框架一起使用

Bootstrap 5
TailwindCSS 3（即将推出功能）

兼容性

使用示例

只需在视图中调用所需的组件，让此包处理耗时较多的 HTML 生成部分。

<x:form::form class="row" method="PUT" :action="route('user.update', $user)" :bind="$user">
    <div class="col-md-6">
        <x:form::input name="name"/>
        <x:form::input type="email" name="email"/>
        <x:form::textarea name="biography" :locales="['fr', 'en']"/>
    </div>
    <div class="col-md-6">
        <x:form::select name="hobbies" :options="[1 => 'Sport', 2 => 'Cinema', 3 => 'Literature', 4 => 'Travel']" caption="Select your favorite hobbies." multiple/>
        <x:form::checkbox name="technologies" :group="[1 => 'Laravel', 2 => 'Bootstrap', 3 => 'Tailwind', 4 => 'Livewire']" inline/>
        <x:form::radio name="gender" :group="[1 => 'Male', 2 => 'Female', 3 => 'Other']" inline/>
        <x:form::toggle-switch name="active"/>
    </div>
    <div class="col-12 mt-2">
        <x:form::button.link class="btn-secondary me-3">{{ __('Cancel') }}</x:form::button.link>
        <x:form::button.submit/>
    </div>
</x:form:form>

然后显示这些组件

安装

您可以通过 composer 安装此包

composer require pojow/laravel-form-components

配置

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag=form-components:config

在其配置中，此包允许您选择要使用的 UI 框架。

请注意，在开始使用此包之前，您必须安装和配置您想要使用的 UI 框架。

视图

您可以将包视图发布出来进行自定义（如果需要的话）

php artisan vendor:publish --tag=form-components:views

组件

表单

组件可以包装在表单组件中。

如果没有设置自定义方法，则默认将设置 GET 方法。

根据定义的表单方法，当需要时将自动生成隐藏的 CSRF 和欺骗方法字段。

您不需要定义 @method() 指令，可以直接在 action 属性中声明您的 PUT、PATCH 或 DELETE 动作。
您不需要定义 @csrf() 指令，它将在 POST、PUT、PATCH 和 DELETE 动作中自动声明。

表单将以默认的 novalidate HTML 属性生成，这阻止了浏览器验证，而是使用服务器端验证（这对于安全问题来说是一个好习惯）。

<x:form::form method="PUT">
    <x:form::input name="first_name"/>
    ...
</x:form::form>

输入和文本域

将输入和文本域添加到您的表单中。

如果您没有为输入设置自定义类型，它将采用默认的 text 类型。

由于单选框、复选框和按钮输入的行为不同，因此必须使用它们各自的组件。

文本域组件可以像输入组件一样使用，但无需声明类型。

<x:form::input type="file" name="avatar"/>
<x:form::input name="first_name"/>
<x:form::input type="email" name="email"/>
...
<x:form::textarea name="description"/>

选择

在您的表单中设置选择组件。

通过提供一个关联的值/标签数组来自动生成选项。

HTML 选择元素默认不接受占位符属性，但是选择组件允许您处理一个类似于占位符的选项，它被添加到其他选项之前。此占位符将像其他组件一样表现。

默认情况下，此选择占位符选项被选中、禁用并隐藏。但是，如果您需要设置一个 nullable 字段等，您将能够允许它被选中。为此，只需将 allowPlaceholderToBeSelected 属性添加到您的组件中即可。

在多选模式下，此包将负责将名称转换为数组名称，因此您不需要手动添加它。

@php($options = [1 => 'Laravel', 2 => 'Bootstrap', 3 => 'Tailwind'])
<x:form::select name="hobby" placeholder="What is your hobby prefered hobby?" :options="$options" selected="1"/>
<x:form::select name="hobbies" :options="$options" :selected="[2, 3]" allowPlaceholderToBeSelected multiple/> {{-- You'll be able to selected the placeholder and the name will be converted to hobbies[] --}}

复选框、开关和单选框

复选框、切换开关和单选组件可供您使用。

由于单选输入从不单独使用，当使用它们时，您必须声明一个必需的 group 属性，并期待一个关联数组，从其中生成单选字段。

关于复选框和切换开关输入，您可以在单选或分组模式下使用它们。要在分组模式下使用它们，您也需要声明一个 group 属性。

在分组模式下，此包将负责将名称转换为数组名称，因此您无需手动添加。

如果您想显示这些输入组件在同一行，请定义一个 inline 属性。

<x:form::checkbox name="newsletter_subscription" :checked="true"/> {{-- 1 generated checkbox --}}
<x:form::checkbox name="technologies" :group="['laravel' => 'Laravel', 'bootstrap' => 'Bootstrap']" :checked="laravel"/> {{-- 2 generated checkboxes --}}
<x:form::toggle-switch name="active" :checked="false" inline/> {{-- 1 generated toggle switch with inline mode --}}
<x:form::toggle-switch name="technologies" :group="['tailwind' => 'Tailwind', 'livewire" => 'Livewire']" :checked="livewire"/> {{-- 2 generated toggle switches --}}
<x:form::radio name="gender" :group="['female' => 'Female', 'male' => 'Male']" :checked="male" inline/> {{-- 2 generated radios with inline mode --}}

按钮

提交和链接按钮组件可用。

提交按钮允许您触发表单，如果没有定义，将提供默认的 __('Submit') 主体。

链接按钮允许您通过提供类似按钮的显示方式，在您的表单中设置 Back 或 Cancel 等操作。作为HTML链接组件，它将通过分析其主体提供默认标题。

默认情况下，如果未定义自定义类属性，这两个组件将设置一个基本背景颜色。

<x:form::form>
    ...
    <div class="d-grid">
        <x:form::button.submit>Submit this form</x:form::submit> {{-- Will provide `btn-primary` class with Bootstrap UI --}}
        <x:form::button.link class="btn-secondary" href="{{ back() }}"> {{-- Will auto-generate `title="Back"` --}}
            <i class="fas fa-undo fa-fw"></i>
            Back
        </x:form::submit>
    </div>
</x:form::form>

如何使用

处理属性和类

提供组件使用 Blade组件构建。

遵循Blade组件的工作方式，您可以设置任何HTML属性和类。

属性将替换默认属性。
类将合并到现有类中。

设置 id

定义组件ID的方式与任何HTML元素相同。

如果没有设置自定义ID，将使用kebab cased <type>-<name> 值生成ID。

<x:form::input id="custom-id" name="first_name"/> {{-- Default id: `input-first-name` --}}

<x:form::textarea id="custom-id" name="first_name"/> {{-- Default id: `textarea-first-name` --}}

启用或禁用输入下边距。

默认情况下，所有输入组件将声明一个下边距，以便正确地在表单中定位自己。

有时您需要禁用此默认下边距：您可以通过将 marginBottom 属性设置为 false 来做到这一点。

<x:form::input name="first_name"/> {{-- Will declare a bottom margin --}}

<x:form::textarea name="first_name" :marginBottom="false"/> {{-- Will not declare any bottom margin --}}

管理标签和占位符

您可以在所有输入组件上定义标签（除了 Radio）。

如果没有定义自定义标签，标签将采用 __('validation.attributes.<name>) 默认值。

遵循相同的行为，所有允许使用 placeholder（包括 Select）的输入组件将提供一个默认的占位符，该占位符将采用 label 值。

您可以通过设置自定义占位符来覆盖此默认值。

您还可以通过将它们设置为 false 来隐藏自动生成的标签和占位符。

<x:form::input name="first_name" label="First Name" placeholder="Please fill your first name..."/> {{-- Will display the custom label and placeholder --}}
<x:form::input name="last_name" :label="false" :placeholder="false"/> {{-- Will hide the label and placeholder --}}
<x:form::input type="tel" name="phone_number"/> {{-- Will display default auto-generated label and placeholder --}}

处理浮动标签显示

此包允许您启用或禁用浮动标签显示。

您可以使用 config('form-components.floating_label') 配置来设置全局浮动标签行为。

您可以在表单级别覆盖所有包含组件的全局行为。

<x:form::form :floatingLabel="true">
    <x:form::input name="first_name"/> {{-- Will display a floating label even if it has been disabled in config --}}
</x:form::form>

最后，您还可以在组件本身上覆盖所有其他定义的行为。

    <x:form::input name="first_name" :floatingLabel="true"/>

设置附加组件

您可以在输入和textarea组件上定义 prepend 和 append HTML附加组件。

    <x:form::input name="" prepend="<i class="fas fa-code fa-fw"></i>"/>
    <x:form::input name="search" append="<i class="fas fa-search fa-fw"></i>"/>

注意：您可以直接使用HTML而不是组件来管理复杂的附加组件。

绑定数据

您可以将Eloquent模型、对象、集合或数组绑定到组件，以自动填充绑定的组件值。

在表单组件上绑定数据将触发其所有包含组件的绑定。

您可以直接在组件上绑定数据并覆盖表单绑定。

在验证错误的情况下，组件将通过覆盖绑定的值来重新填充旧值。

对于特定用例，您还可以使用 @bind($boundDataBatch) 和 @endbind Blade指令来绑定一组组件。

@php
    $dataBatch1 = ['description' => 'A wonderful description'];
    $dataBatch2 = ['first_name' => 'John', 'last_name' => 'Bonham'];
@endphp
<x:form::form :bind="$user">
    <x:form::input type="email" name="email"/> {{-- Will set the value from `$user->email` --}}
    <x:form::textarea name="description" :bind="$dataBatch1"/> {{-- Will set the value from `$dataBatch1['description`] --}}
    @bind($dataBatch2)
        <x:form::input name="first_name"/> {{-- Will set the value from `$dataBatch2['first_name`] --}}
        <x:form::input name="last_name"/> {{-- Will set the value from `$dataBatch2['last_name`] --}}
    @endbind
</x:form::form>

设置自定义值

可以通过在组件上设置自定义值来覆盖数据绑定。

@php($data = ['description' => 'A wonderful description'];)
<x:form::form :bind="$user">
    ...
    <x:form::textarea
        name="description"
        :bind="$user"
        :value="$data['description']"/> {{-- Will set the value from `$data['description`] --}}
</x:form::form>

处理验证状态和错误

当触发验证错误时，组件将能够显示或隐藏其成功/错误状态和错误消息。

如果启用验证成功显示，组件仅在表单中的其他组件被检测为无效时才被标记为有效
如果启用验证失败显示，错误组件将被标记为无效，并显示相关错误消息

您可以在不同级别控制此行为

使用 config('form-components.display_validation_success') 和 config('form-components.display_validation_failure') 定义全局默认行为
在表单上自定义此行为，并将其应用于所有包含的组件
直接在组件上设置特定行为

<x:form::form displayValidationSuccess="false" displayValidationFailure="false">
    <x:form::input type="email" name="email"/> {{-- Disabled success/error statuses and error message --}}
    <x:form::textarea
        name="description"
        displayValidationSuccess="true"
        displayValidationFailure="true"/> {{-- Enabled success/error statuses and error message --}}
</x:form::form>

您还可以自定义用于确定表单组件成功/错误状态和错误消息的错误包。

<x:form::form errorBag="form_error_bag"> {{-- Error bag for all components within the form --}}
    @errorbag('group_error_bag') {{-- Error bag for a group of components --}}
        <x:form::input name="first_name"/>
        <x:form::input name="last_name"/>
    @enderrorbag
    <x:form::input type="email" name="email" errorBag="component_error_bag"/> {{-- Error bag for a specific component --}}
    ...
</x:form::form>

添加标题

通过添加标题，帮助用户并在组件下方显示附加说明。

    <x:form::input name="name" caption="Please fill this input with your full name."/>

激活多语言模式

在 input 和 textarea 组件上激活多语言模式，以利用以下功能

组件重复：每个区域设置将显示一个组件
名称本地化：name="description" 将转换为 name="description[<locale>]"
默认标签和错误消息本地化：用于生成默认标签和错误消息的 __(validation.attributes.name) 翻译将附加 (<LOCALE>)

<x:form::input name="name" :locales="['fr', 'en']"/>
<x:form::textarea name="description" :locales="['fr', 'en']"/>

测试

composer test

更新日志

请参阅变更日志了解最近更改的详细信息。

贡献

请参阅贡献指南了解详细信息。

安全漏洞

请查看我们的安全策略了解如何报告安全漏洞。

鸣谢

许可证

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

pojow / laravel-form-components

维护者

详细信息