创建面板插件

#前言

继续之前，请先阅读面板插件开发以及入门指南文档。

#简介

本教程中，我们将创建一个简单的插件，添加一个可以在表单中使用的新表单组件。这也意味着用户可以在他们的面板中使用它。

该插件的最终代码可以在此 https://github.com/awcodes/clock-widget。

#步骤 1：创建插件

首先，我们将使用入门指南中概述的步骤创建插件。

#步骤 2：清洁代码

接下来，我们对插件代码进行清洁，移除不需要的模板代码。这看似很多，这是因为我们准备编写的是一个简单的插件，因此我们可以移除许多样板代码。

移除以下目录和文件：

1. config
2. database
3. src/Commands
4. src/Facades
5. stubs

由于我们的插件没有功能所需的任何设置或其他方法，我们还可以删除 ClockWidgetPlugin.php 文件。

由于 Filament 建议用户使用自定义的 Filament 主题来设计插件，我们将删除在插件中使用 CSS 所需的文件。这是可选的，如果你愿意，你仍然可以使用 CSS，但不建议使用。

1. resources/css
2. postcss.config.js

然后清理 composer.json 文件，移除不需要的选项。

"autoload": {
    "psr-4": {
        // 删除数据库工厂
        "Awcodes\\ClockWidget\\Database\\Factories\\": "database/factories/"
    }
},
"extra": {
    "laravel": {
        // 删除 Facade
        "aliases": {
            "ClockWidget": "Awcodes\\ClockWidget\\Facades\\ClockWidget"
        }
    }
},

最后异步更新 package.json 文件，删除不需要的选项。使用如下内容替换掉 package.json 的内容：

{
    "private": true,
    "type": "module",
    "scripts": {
        "dev": "node bin/build.js --dev",
        "build": "node bin/build.js"
    },
    "devDependencies": {
        "esbuild": "^0.17.19"
    }
}

然后安装依赖。

npm install

你也可以删除测试目录和文件，不过虽然本例中不会用到，我们还是暂时留下它们。强烈建议你为插件编写测试。

#步骤 3：设置 provider

既然我们已经清洁了插件代码，我们可以开始添加自己的代码了。src/ClockWidgetServiceProvider.php 文件中也有许多样板代码，让我们全部删除并从头开始。

我们需要能够在面板中注册我们的 Widget，并在使用 Widget 时加载我们的 Alpine 组件。为此，我们需要将以下内容添加到服务提供者的 packageBooted 方法中。这将在 Livewire 注册我们的 Widget 组件，在 Filament Asset Manager 注册我们的 Alpine 组件。

use Filament\Support\Assets\AlpineComponent;
use Filament\Support\Facades\FilamentAsset;
use Livewire\Livewire;
use Spatie\LaravelPackageTools\Package;
use Spatie\LaravelPackageTools\PackageServiceProvider;

class ClockWidgetServiceProvider extends PackageServiceProvider
{
    public static string $name = 'clock-widget';

    public function configurePackage(Package $package): void
    {
        $package->name(static::$name)
            ->hasViews()
            ->hasTranslations();
    }

    public function packageBooted(): void
    {
        Livewire::component('clock-widget', ClockWidget::class);

        // Asset Registration
        FilamentAsset::register(
            assets:[
                 AlpineComponent::make('clock-widget', __DIR__ . '/../resources/dist/clock-widget.js'),
            ],
            package: 'awcodes/clock-widget'
        );
    }
}

#步骤 4：创建 Widget

现在我们可以创建我们的 Widget 了。我们首先需要在 ClockWidget.php 文件中扩展 Filament 的 Widget 类，并告诉它在哪里可以找到 Widget 的视图。由于我们使用 PackageServiceProvider 注册我们的视图，我们可以使用 :: 语法告诉 Filament 在哪里找到视图。

use Filament\Widgets\Widget;

class ClockWidget extends Widget
{
    protected static string $view = 'clock-widget::widget';
}

接下来，我将为 Widget 创建视图。新建 resources/views/widget.blade.php 视图并添加如下代码。我们使用 Filament 的 Blade 组件来节省为 Widget 编写 html 的时间。

我们使用异步 Alpine 来加载我们的 Alpine 组件，所以我们需要将 x-load 属性添加到 div，以告知 Alpine 加载组件。更多详情请查阅核心概念文档。

<x-filament-widgets::widget>
    <x-filament::section>
        <x-slot name="heading">
            {{ __('clock-widget::clock-widget.title') }}
        </x-slot>

        <div
            x-load
            x-load-src="{{ \Filament\Support\Facades\FilamentAsset::getAlpineComponentSrc('clock-widget', 'awcodes/clock-widget') }}"
            x-data="clockWidget()"
            class="text-center"
        >
            <p>{{ __('clock-widget::clock-widget.description') }}</p>
            <p class="text-xl" x-text="time"></p>
        </div>
    </x-filament::section>
</x-filament-widgets::widget>

接下来，我们需要在 src/js/index.js 中编写 Alpine 组件。并且使用 npm run build 编译资源：

export default function clockWidget() {
    return {
        time: new Date().toLocaleTimeString(),
        init() {
            setInterval(() => {
                this.time = new Date().toLocaleTimeString();
            }, 1000);
        }
    }
}

同时，我们需要为 Widget 中的文本添加翻译，这样用户可以将插件翻译成他们自己的语言。我们需要将翻译文件添加到 resources/lang/en/widget.php。

return [
    'title' => 'Clock Widget',
    'description' => 'Your current time is:',
];

#步骤 5：更新 README

更新 README.md 文件以包含如何安装插件和其他你希望与用户分享的信息，比如，如何在项目中使用该插件。如下：

// 在面板提供者中添加插件/Wiget：

use Awcodes\ClockWidget\ClockWidgetWidget;

public function panel(Panel $panel): Panel
{
    return $panel
        ->widgets([
            ClockWidgetWidget::class,
        ]);
}

完毕，现在用户可以安装插件，并且在项目上使用了。

Edit on GitHub

Still need help? Join our Discord community or open a GitHub discussion