ralphjsmit/tall-interactive

轻松创建表单、模态框和滑入效果。

维护者

详细信息

github.com/ralphjsmit/tall-interactive

主页

源代码

问题

安装次数: 55,131

依赖者: 3

建议者: 0

安全性: 0

星级: 120

关注者: 5

分支: 9

公开问题: 1

0.10.0 2024-03-14 10:00 UTC

Requires

Requires (Dev)

MIT eb762a2a6128adef20821567ffbba2d98bd3d9e1

  • Ralph J. Smit <rjs.woop@ralphjsmit.com>

laravelralphjsmittall-interactive

This package is auto-updated.

Last update: 2024-08-29 05:44:29 UTC

README

tall-interactive

轻松创建表单、模态框和滑入效果。

此包允许您轻松创建漂亮的表单、模态框和滑入效果。它利用了 Filament Forms 包来创建表单，并利用了 TALL-stack 来设计。

重要

此包仅适用于 Filament V2 和 Livewire V2。自 Filament V3 以来，实现模态框和滑入效果更好的方法是利用新的 Filament Actions。

Run tests

安装

您可以通过 composer 安装此包

composer require ralphjsmit/tall-interactive

设置

此包需要以下依赖项

  • Laravel Livewire
  • Alpine.js
  • Tailwind CSS
  • Filament Forms
  • Toast 通知（不是必需的，但非常方便）

您可以选择手动安装它们或跳转到 快速安装部分 来安装新项目。

Laravel Livewire

如果您还没有这样做，请按照 Laravel Livewire 安装说明 进行操作。

Alpine.js、Tailwind、Filament Forms

请按照 Filament Forms 安装说明 安装 Alpine.js、Tailwind CSS 和 Filament Forms。

将以下内容添加到您的 tailwind.config.js 文件的 content 键中

module.exports = {
    content: [
        './vendor/ralphjsmit/tall-interactive/resources/views/**/*.blade.php',
        // All other locations
    ],
///

Toast 通知

使用 Toast TALL 通知包 不是必需的，但如果您需要向用户发送通知，例如在提交表单时，则推荐使用。

如果您决定使用 Toast，请按照他们的 设置说明 进行操作。

Tall Interactive

安装包并设置依赖项后，将以下代码添加到您的 Blade 文件中，以便在每页上加载。例如，在您的 layouts/app.blade.php 视图中

<x-tall-interactive::actionables-manager />

现在您已经准备好开始构建您的第一个可操作项了！

快速安装

如果您想要一个更快的安装过程，可以查看我的 ralphjsmit/tall-install 包。此包提供了一个简单的命令，可以在纯 Laravel 安装中运行上述所有依赖项的安装过程。

工作原理如下

# First, create a new plain Laravel installation, for example with:

laravel new name 
# OR: composer create-project laravel/laravel name 

# Next, require the `tall-install` package and run the `php artisan tall-install` command:
composer require ralphjsmit/tall-install
composer dump-autoload
php artisan tall-install

tall-install 命令还有一些额外的选项可供您使用，例如安装 Pest、Browsersync 和 DDD。请查看文档 了解详情。

用法

您可以使用三个东西构建一个 模态框、一个 滑入效果 或一个 内联表单（统称为 'actionables'）

  • 使用 Filament Form
  • 使用 Livewire 组件
  • 使用 自定义 Blade 内容

创建 Filament 表单

要开始构建我们的第一个可操作项，让我们先做一些准备工作。在您的 app/Forms 目录中创建一个新文件（自定义命名空间也行）。您可以将其命名为 UserForm 或您喜欢的任何名称。

将以下内容添加到文件中

<?php

namespace App\Forms;

use RalphJSmit\Tall\Interactive\Forms\Form;

class UserForm extends Form 
{
    public function getFormSchema(): array
    {
        return [];
    }

    public function submit(): void
    {
        //
    }

    public function mount(): void 
    {
        //
    }
    
    /** Only applicable for Modals and SlideOvers */
    public function onOpen(): void 
    {
        //
    }
}

构建您的表单

使用 Filament 创建表单非常简单。表单的 字段类 位于表单类的 getFormSchema() 方法中。

对于所有可用的字段，请查看 Filament 文档。

public function getFormSchema(Component $livewire): array
{
    return [
        TextInput::make('email')
            ->label('Enter your email')
            ->placeholder('john@example.com')
            ->required(),
        Grid::make()->schema([
            TextInput::make('firstname')
                ->label('Enter your first name')
                ->placeholder('John'),
            TextInput::make('lastname')
                ->label('Enter your last name')
                ->placeholder('Doe'),
        ]),
        TextInput::make('password')
            ->label('Choose a password')
            ->password(),
        MarkdownEditor::make('why')
            ->label('Why do you want an account?'),
        Placeholder::make('open_child_modal')
            ->disableLabel()
            ->content(
                new HtmlString('Click <button onclick="Livewire.emit(\'modal:open\', \'create-user-child\')" type="button" class="text-primary-500">here</button> to open a child modal🤩')
            ),
    ];
}

默认值与模型

字段值存储在 $livewire 组件的 $data 数组属性中。您可以使用 Filament 的 ->default() 方法设置默认值。

public function getFormSchema(Component $livewire): array
{
    return [
        TextInput::make('year')
            ->label('Pick your year of birth')
            ->default(now()->subYears(18)->format('Y'))
            ->required(),
    ];
}

您还可以在表单类中添加一个 fill() 方法。这将传递给 $this->form->fill() 方法，可用于预填充值。

以下是一个基于 Blade 组件参数预填充表单的示例。

    public int $personId;
    
    public function mount(array $params): void
    {
        $this->personId = $params['personId'];
    }
    
    public function fill(): array
    {
        $person = Person::find($this->personId);
        
        return [
            'year' => $person->birthdate->format('Y'),
        ];
    }

提交表单

您可以使用 submit() 方法 来提供提交表单的逻辑。

use Illuminate\Support\Collection;

public function submit(Collection $state): void
{
    User::create($state->all());

    toast()
        ->success('Thanks for submitting the form! (Your data isn\'t stored anywhere.')
        ->push();
}

添加自定义验证消息

您可以通过实现 getErrorMessages() 函数来注册自定义验证消息。

public function getErrorMessages(): array
{
    return [
        'email.required' => 'Please fill in your e-email',
        'age.required' => 'Please enter your age',
        'age.numeric' => 'Your age must be a number',
    ];
}

表单类中的依赖注入

tall-interactive 包还提供了对表单类中所有方法的 依赖注入，类似于 Filament 表单。

您可以在以下方法中指定以下变量

  1. $livewire 用于获取 当前的 Livewire 实例
  2. $model 用于获取 当前模型（如果有）
  3. $formClass 用于访问 当前表单类的实例。您可以使用此来设置和获取参数（请参阅存储数据）。
  4. $formVersion 用于访问 当前的表单版本。您可以使用此来区分不同版本的表单（如同一表单的“创建”和“编辑”版本）。
  5. $state 用于访问 当前提交的表单数据。这是一个集合。仅在 submit 方法中可用。
  6. $close 用于获取一个闭包，允许您 关闭一个可操作项。您可以将包含可操作项 id 的字符串传递给闭包，以关闭该可操作项。默认为当前可操作项。如果您传递了一个不存在的 id，则不会发生任何操作。
  7. $forceClose 用于获取一个闭包，允许您 关闭所有可操作项。
  8. $params 用于获取包含传递给可操作项 Blade 组件的所有附加参数的数组。

使用 $close() 和 $forceClose() 闭包是一种非常 高级的自定义方式，可以指定哪些可操作项应该打开，哪些不应该。

您可以随意混合和匹配这些依赖项，并且只包括您需要的那些。类似于Filament 的闭包自定义。

例如

use Closure;
use Livewire\Component;
use App\Models\User;

public function submit(Component $livewire, User $model, Collection $state, Closure $close, Closure $forceClose): void 
{
    $model
        ->fill($state->except('password'))
        ->save();

    if ($state->has('password')) {
        $model->update(
            $state->only('password')->all()
        );
    }
    
    /* Close current actionable */
    $close(); 
    
    /* Close another actionable */
    $close('another-peer-actionable'); 
    
    /* Close all open actionables */
    $forceClose();
}

使用模态框和滑动覆盖

为了在页面上 打开一个模态框，在页面上某处包含以下内容

<x-tall-interactive::modal id="create-user" />

如果您想 打开一个滑动覆盖 而不是模态框，请使用以下标记

<x-tall-interactive::slide-over id="create-user" />

模态框组件和滑动覆盖组件工作方式完全相同。

这里唯一的 必需参数 是可操作项的 id。这个 id 是必需的，因为您需要它来触发打开可操作项的 Livewire 事件。每个页面上可操作项的 id 应该是不同的，否则多个可操作项将同时打开。

您可以通过发出带有 id 作为第一个参数的 modal:open 或 slideOver:open 事件来 打开一个可操作项。

<button onclick="Livewire.emit('modal:open', 'create-user')" type="button" class="...">
    Open Modal
</button>

您可以通过发出带有 id 作为第一个参数的 modal:close 或 slideOver:close 事件来 关闭一个可操作项。

<button onclick="Livewire.emit('modal:close', 'create-user')" type="button" class="...">
    Close modal
</button>

您可以通过发出带有 id 作为第一个参数的 :close 事件来 关闭一个未知类型的可操作项。

<button onclick="Livewire.emit(':close', 'create-user')" type="button" class="...">
    Close modal
</button>

对于以下所有示例，您都可以始终将 modal 更改为 slide-over 来使用滑动覆盖。

Filament Forms

当前可操作项为空。让我们通过 显示我们的表单 来修复它。为了显示表单，请添加 form 属性。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
/>

现在，当你 触发 modal:open 事件 时，模态将 包含一个漂亮的表单。

Livewire

您可以使用 livewire 属性指定要使用的 Livewire 组件名称，而不是表单。

<x-tall-interactive::modal
    id="create-user"
    livewire="users.edit"
/>

如果您同时指定了 form 和 livewire 属性，则只会显示 form。

Blade

您还可以通过将自定义 Blade 内容放入组件槽位来为可操作项提供内容。

<x-tall-interactive::modal id="create-user">

    <p>My custom Blade content in this actionable!<p>

</tall-interactive::modal>

建议不要使 Blade 内容过大。几段文字即可，但显示一篇 10,000 字的文章可能会造成显著的延迟。

配置属性

以下 属性 可用于 配置您的可操作项。

在成功提交表单后关闭模态

如果您指定了 closeOnSubmit 属性，则可操作项将在提交后 自动关闭。此属性默认为 true，这意味着在成功提交表单后，可操作项将关闭。

如果您指定了 forceCloseOnSubmit 属性，则在成功提交此表单时，将 关闭所有可操作项。这对于像这样的情况很有用：编辑用户 > 删除用户 > 提交。此属性默认为 false。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    closeOnSubmit="false"
/>

如果您需要更高级的配置，以确定哪些可操作项要关闭以及哪些要保持打开，您应在表单类的 submit() 方法中注入并使用 $close() 和 $forceClose()。

添加标题

您可以使用 title 属性指定表单的 标题。如果您省略了 title 属性，则标题将不可见。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    title="Create a user"
/>

添加描述

您可以使用 description 属性指定表单的 描述。如果您省略了 description 属性，则描述将不可见。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    title="Create a user"
    description="Use this form to grant a user access to your system."
/>

提交按钮上的文本

您可以通过指定 submitWith 属性来设置 提交按钮上的文本。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    submitWith="Create user"
/>

在提交前关闭表单

您可以通过指定 dismissable 属性来允许在提交之前取消（关闭）可操作项。默认情况下，此功能已禁用。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    dismissable
/>

您可以使用 dismissableWith 属性来指定可操作项关闭按钮的 文本。默认文本为 '关闭'。

如果您指定了 dismissableWith 属性，则允许省略 dismissable 属性。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    dismissableWith="Go back"
/>

隐藏按钮

您可以通过指定 hideControls 属性来隐藏可操作项底部的 按钮。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    hideControls
/>

设置最大宽度

您可以通过指定 maxWidth 属性来设置可操作项的 最大宽度。允许的值有：sm、md、lg、xl、2xl、3xl、4xl、5xl、6xl、7xl。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    maxWidth="2xl"
/>

模型绑定

您可以为表单提供一个（Eloquent）模型，可用于编辑表单等。

@foreach (\App\Models\User::get() as $user)
    <x-tall-interactive::modal
        id="edit-user"
        :form="\App\Forms\UserForm::class"
        :model="$user"
    />
@endforeach

有关绑定到模型属性的说明，请参阅本节。

自定义参数

您可以通过任何自定义参数传递给 Blade 组件，方式不限。这些参数收集在一个数组中，可以在您的表单中使用。

<x-tall-interactive::modal
    id="create-user"
    :form="\App\Forms\UserForm::class"
    closeOnSubmit
    x="test"
    :y="8*8"
    z
/>
public function getFormSchema(array $params): array
{
    // $params
    // [ 'x' => 'test', 'y' => 64, 'z' => true ]
    
    return [
        // ..
    ];
}

内联表单

您还可以在页面如上显示 内联表单。

<x-tall-interactive::inline-form />

对于内联表单，您 不需要指定 id。

内联表单需要以下参数

  1. container
  2. controlsDesign
  3. form
  4. title
  5. description
  6. submitWith
  7. hideControls
  8. maxWidth
  9. model

参数 3-9 与上述说明相同，因此这里不再重复。

将内联表单放入容器中

您可以通过指定container属性来将内联表单放入一个漂亮的容器中。容器是一个简单的包装器，它将表单放在一个带有漂亮阴影的白色框中。

更改控件设计

您可以通过指定controlsDesign来更改表单底部的按钮设计。它可以是两个值之一：minimal和classic。默认情况下为minimal。

高级使用

存储数据

在某些情况下，在表单类的实例中存储数据可能很有用。您可以在后续过程中使用这些数据，例如在提交表单时。

您可以在表单类上添加public属性来存储数据。这样做的一个好地方是mount()方法，如下所示。

挂载表单

您可以使用表单类上的mount()方法来挂载表单。这在第一次调用时存储/设置表单类中的数据可能很有用。

您还可以使用所有可用的依赖注入功能（有关所有可能参数的列表，请参阅上面）

public User $user;
public string $x = '';

public function mount(array $params, User $model): void
{
    $this->user = $model;
    $this->x = $params['x'];
}
                                                                  
public function getFormSchema(): array
{
    return [
        Hidden::make('user_id')->default($this->user->id)
    ];
}

响应事件

您可以在表单类上添加一个onOpen()方法来响应可操作项打开的事件。正如您所预期的，此方法仅适用于模态和滑动覆盖。

public function onOpen(): void
{
    // ...
}

您还可以在打开表单时传递参数

<button onclick="Livewire.emit('modal:open', 'create-user', 8, 'admin')" type="button" class="...">
    Open Modal
</button>

使用$eventParams变量来访问传递给事件的参数。

public User $user;
public array $prefilledValues = [];

public function onOpen(array $eventParams, self $formClass): void
{
    $formClass->user = User::find($eventParams[0]);
    $formClass->prefilledValues['type'] = $eventParams[1];
}

自定义视图

可选地，您可以使用（不推荐，它们可能会过时）来发布视图

php artisan vendor:publish --tag="tall-interactive-views"

一般

🐞 如果您发现一个错误，请提交详细的错误报告，我将尽快修复它。

🔐 如果您发现一个漏洞，请查阅我们的安全策略。

🙌 如果您想做出贡献，请提交一个拉取请求。所有PR都将得到充分认可。如果您不确定我是否会接受您的想法，请随时联系我！

🙋‍♂️ Ralph J. Smit