开发独立插件 - 核心概念

前言

继续之前，请先移步到面板插件开发及开始向导阅读文档。

概述

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

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

步骤 1: 创建插件

首先，我们将使用开始向导中提到的步骤创建插件。

步骤 2: 清理

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

删除下列目录和文件：

bin
config
database
src/Commands
src/Facades
stubs
tailwind.config.js

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

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

通常，Filament v3 建议用户使用自定义的 Filament 主题来设计插件的样式，但为了示例，让我们提供自己的样式表，该样式表可以使用 Filament v3 中的新 x-load 功能异步加载。因此，让我们更新 package.json 文件，引入 cssnano、postpass、postpass-cli 和 postpass-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": "^12.0.0"
    }
}
{
    "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": "^12.0.0"
    }
}

然后，我们需要安装依赖。

npm install
npm install

我们也需要更新 postcss.config.js 文件去配置 postcss。

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

你可能也想删除测试目录及其文件，不过我们暂时先把它们留着，虽然我们在这个例子中我们不会使用测试，我还是强烈推荐为你的插件编写测试。

步骤 3: 服务提供者

清理完后，我们就可以开始添加代码了。src/HeadingServiceProvider 文件中的样板代码中有很多内容，因此，我们删除所有内容，从头开始。

我们需要使用 Filament 资源管理器(Filament Asset Manager)注册样式表，这样我们就可以在 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');
    }
}
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\Forms\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]);
    }
 
    protected function setUp(): void
    {
        parent::setUp();
 
        $this->dehydrated(false);
    }
 
    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;
    }
}
namespace Awcodes\Headings;

use Closure;
use Filament\Forms\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]);
    }

    protected function setUp(): void
    {
        parent::setUp();

        $this->dehydrated(false);
    }

    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 }}>
@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;
     }
}
.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
npm run build

步骤 7: 更新 Readme

你需要更新 README.md 文件，使之包含如何安装插件的说明以及其他你想分享给用户的信息，比如，如何在项目中使用该组件。示例：

use Awcodes\Headings\Heading;
 
Heading::make(2)
    ->content('Product Information')
    ->color(Color::Lime),
use Awcodes\Headings\Heading;

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

就是这样，用户可以安装这个插件并在他们的项目中使用。

Edit on GitHub

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

#前言

#概述

#步骤 1: 创建插件

#步骤 2: 清理

#步骤 3: 服务提供者

#步骤 4: 创建组件

#步骤 5: 渲染组件

#步骤 6: 添加一些样式

#步骤 7: 更新 Readme

前言