构建一个面板插件

前言

请阅读有关面板插件开发的文档和入门指南再继续前。

引言

在本演练中，我们将构建一个简单的插件，它添加了一个可在表单中使用的新表单字段。这也意味着它将可供用户在其面板中使用。

您可以在以下地址找到此插件的最终代码：https://github.com/awcodes/clock-widget。

步骤 1: 创建插件

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

步骤 2: 清理

接下来，我们将清理插件以移除不需要的样板代码。这看起来可能很多，但由于这是一个简单的插件，我们可以移除大量的样板代码。

删除以下目录和文件：

配置
数据库
src/命令
源/外观
存根

鉴于我们的插件没有任何功能所需的设置或额外方法，我们也可以移除 ClockWidgetPlugin.php 文件。

ClockWidgetPlugin.php

鉴于 Filament 建议用户使用自定义的 Filament 主题来为其插件设置样式，我们将移除插件中使用 CSS 所需的文件。这是可选的，如果你愿意，你仍然可以使用 CSS，但不建议这样做。

资源/CSS
postcss.config.js

现在我们可以清理我们的 composer.json 文件以移除不需要的选项。

json

"autoload": {
    "psr-4": {
        // We can remove the database factories
        "Awcodes\\ClockWidget\\Database\\Factories\\": "database/factories/"
    }
},
"extra": {
    "laravel": {
        // We can remove the facade
        "aliases": {
            "ClockWidget": "Awcodes\\ClockWidget\\Facades\\ClockWidget"
        }
    }
},

最后一步是更新 package.json 文件，以删除不需要的选项。将 package.json 的内容替换为以下内容。

json

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

然后我们需要安装我们的依赖项。

bash

npm install

您也可以删除 Testing 目录和文件，但我们暂时会保留它们，尽管在此示例中我们不会使用它们，并且我们强烈建议您为您的插件编写测试。

步骤 3: 设置提供程序

既然我们已经清理好了插件，就可以开始添加代码了。src/ClockWidgetServiceProvider.php 文件中的样板代码内容很多，所以，让我们删除所有内容，从头开始。

在此示例中，我们将注册一个异步 Alpine 组件。由于这些资产仅在请求时加载，我们可以像往常一样在packageBooted()方法中注册它们。如果您正在注册资产，例如 CSS 或 JS 文件，无论是否使用都会在每个页面上加载，您应该在Plugin配置对象的register()方法中注册它们，使用$panel->assets()。否则，如果您在packageBooted()方法中注册它们，它们将被加载到每个面板中，无论该插件是否已为该面板注册。

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

php

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: 创建小部件

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

php

use Filament\Widgets\Widget;

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

接下来，我们需要为我们的组件创建视图。在 resources/views/widget.blade.php 创建一个新文件并添加以下代码。我们将利用 Filament 的 Blade 组件，以节省为该组件编写 HTML 的时间。

我们正在使用异步 Alpine 来加载我们的 Alpine 组件，所以我们需要添加 x-load 属性到 div，以告诉 Alpine 加载我们的组件。你可以在核心概念文档部分了解更多信息。

blade

<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 构建我们的资产。

javascript

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

我们还应该为小部件中的文本添加翻译，以便用户可以将其翻译成自己的语言. 我们会将翻译添加到 resources/lang/en/widget.php.

php

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

步骤 5: 更新你的 README

您会希望更新您的 README.md 文件，以包含关于如何安装您的插件的说明，以及您希望与用户分享的任何其他信息，例如如何在他们的项目中使用它。例如：

php

// Register the plugin and/or Widget in your Panel provider:

use Awcodes\ClockWidget\ClockWidgetWidget;

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

并且，就是这样，我们的用户现在可以安装我们的插件并在他们的项目中使用它了。

前言

请阅读有关面板插件开发的文档和入门指南再继续前。

引言

在本演练中，我们将构建一个简单的插件，它添加了一个可在表单中使用的新表单字段。这也意味着它将可供用户在其面板中使用。

您可以在以下地址找到此插件的最终代码：https://github.com/awcodes/clock-widget。

步骤 1: 创建插件

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

步骤 2: 清理

接下来，我们将清理插件以移除不需要的样板代码。这看起来可能很多，但由于这是一个简单的插件，我们可以移除大量的样板代码。

删除以下目录和文件：

配置
数据库
src/命令
源/外观
存根

鉴于我们的插件没有任何功能所需的设置或额外方法，我们也可以移除 ClockWidgetPlugin.php 文件。

ClockWidgetPlugin.php

资源/CSS
postcss.config.js

现在我们可以清理我们的 composer.json 文件以移除不需要的选项。

json

"autoload": {
    "psr-4": {
        // We can remove the database factories
        "Awcodes\\ClockWidget\\Database\\Factories\\": "database/factories/"
    }
},
"extra": {
    "laravel": {
        // We can remove the facade
        "aliases": {
            "ClockWidget": "Awcodes\\ClockWidget\\Facades\\ClockWidget"
        }
    }
},

最后一步是更新 package.json 文件，以删除不需要的选项。将 package.json 的内容替换为以下内容。

json

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

然后我们需要安装我们的依赖项。

bash

npm install

您也可以删除 Testing 目录和文件，但我们暂时会保留它们，尽管在此示例中我们不会使用它们，并且我们强烈建议您为您的插件编写测试。

步骤 3: 设置提供程序

php

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: 创建小部件

php

use Filament\Widgets\Widget;

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

blade

<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 构建我们的资产。

javascript

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

我们还应该为小部件中的文本添加翻译，以便用户可以将其翻译成自己的语言. 我们会将翻译添加到 resources/lang/en/widget.php.

php

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

步骤 5: 更新你的 README

php

// Register the plugin and/or Widget in your Panel provider:

use Awcodes\ClockWidget\ClockWidgetWidget;

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

并且，就是这样，我们的用户现在可以安装我们的插件并在他们的项目中使用它了。

文档导航

前言

引言

步骤 1: 创建插件

步骤 2: 清理

步骤 3: 设置提供程序

步骤 4: 创建小部件

步骤 5: 更新你的 README

前言

引言

步骤 1: 创建插件

步骤 2: 清理

步骤 3: 设置提供程序

步骤 4: 创建小部件

步骤 5: 更新你的 README