创建独立插件

前言

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

简介

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

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

步骤 1：创建插件

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

步骤 2：清洁代码

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

移除以下目录和文件：

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

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

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

通常情况下，Filament 建议用户使用自定义 Filament 主题来渲染他们的插件样式，此处为了举例，让我们提供自己的样式表，它可以使用 Filament v3 引入的 x-load 新特性异步加载。因此，我们来更新 package.json 文件使之包含 cssnano、postcss、postcss-cli 和 postcss-nesting 以创建我们的样式表。

{
    "private": true,
    "scripts": {
        "build": "postcss resources/css/index.css -o resources/dist/headings.css"
    },
    "devDependencies": {
        "cssnano": "^6.0.1",
        "postcss": "^8.4.27",
        "postcss-cli": "^10.1.0",
        "postcss-nesting": "^13.0.0"
    }
}

然后安装依赖。

npm install

我们同时需要更新 postcss.config.js 文件来配置 postcss。

module.exports = {
    plugins: [
        require('postcss-nesting')(),
        require('cssnano')({
            preset: 'default',
        }),
    ],
};

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

步骤 3：设置 provider

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

我们需要使用 Filament Asset 管理器来注册我们的样式表，使之可以在我们 Blade 视图中按需加载。为此，我们需要在我们的服务提供者中添加以下内容到 packageBooted 方法。

***请注意 loadedOnRequest() 方法。它很重要，因为它告诉 Filament 按需加载样式表。 ***

namespace Awcodes\Headings;

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

class HeadingsServiceProvider extends PackageServiceProvider
{
    public static string $name = 'headings';

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

    public function packageBooted(): void
    {
        FilamentAsset::register([
            Css::make('headings', __DIR__ . '/../resources/dist/headings.css')->loadedOnRequest(),
        ], 'awcodes/headings');
    }
}

步骤 4：创建组件

接下来，我们需要创建新的组件。新建文件 src/Heading.php 并添加如下代码。

namespace Awcodes\Headings;

use Closure;
use Filament\Schemas\Components\Component;
use Filament\Support\Colors\Color;
use Filament\Support\Concerns\HasColor;

class Heading extends Component
{
    use HasColor;

    protected string | int $level = 2;

    protected string | Closure $content = '';

    protected string $view = 'headings::heading';

    final public function __construct(string | int $level)
    {
        $this->level($level);
    }

    public static function make(string | int $level): static
    {
        return app(static::class, ['level' => $level]);
    }

    public function content(string | Closure $content): static
    {
        $this->content = $content;

        return $this;
    }

    public function level(string | int $level): static
    {
        $this->level = $level;

        return $this;
    }

    public function getColor(): array
    {
        return $this->evaluate($this->color) ?? Color::Amber;
    }

    public function getContent(): string
    {
        return $this->evaluate($this->content);
    }

    public function getLevel(): string
    {
        return is_int($this->level) ? 'h' . $this->level : $this->level;
    }
}

步骤 5：渲染组件

接下来，我们需要为组件创建视图。新建文件 resources/views/heading.blade.php 并添加如下代码。

我们使用 x-load 类异步加载样式表，因此，它只会在有需要时加载。了解更多这方面信息，请查阅核心概念区域的文档。

@php
    $level = $getLevel();
    $color = $getColor();
@endphp

<{{ $level }}
    x-data
    x-load-css="[@js(\Filament\Support\Facades\FilamentAsset::getStyleHref('headings', package: 'awcodes/headings'))]"
    {{
        $attributes
            ->class([
                'headings-component',
                match ($color) {
                    'gray' => 'text-gray-600 dark:text-gray-400',
                    default => 'text-custom-500',
                },
            ])
            ->style([
                \Filament\Support\get_color_css_variables($color, [500]) => $color !== 'gray',
            ])
    }}
>
    {{ $getContent() }}
</{{ $level }}>

步骤 6：添加样式

然后，我们来为字段提供一些自定义样式。我们将添加如下内容到 resources/css/index.css 并运行 npm run build 来编译 CSS。

.headings-component {
    &:is(h1, h2, h3, h4, h5, h6) {
         font-weight: 700;
         letter-spacing: -.025em;
         line-height: 1.1;
     }

    &h1 {
         font-size: 2rem;
     }

    &h2 {
         font-size: 1.75rem;
     }

    &h3 {
         font-size: 1.5rem;
     }

    &h4 {
         font-size: 1.25rem;
     }

    &h5,
    &h6 {
         font-size: 1rem;
     }
}

然后，我们需要编译样式表。

npm run build

步骤 7：更新 README

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

use Awcodes\Headings\Heading;

Heading::make(2)
    ->content('Product Information')
    ->color(Color::Lime),

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