README

介绍

Widget Package 是一个简单但功能强大的 Laravel 扩展包，允许开发者创建可重用的组件，以方便在应用程序中创建。这些组件可以在 Blade 视图中任何地方使用，这使得管理复杂的用户界面、构建动态内容和保持关注点分离变得更加容易。该包旨在与小型和大型项目兼容，包括使用 nwidart/laravel-modules 构建的应用模块。

特性

简单组件创建

创建可以在 Blade 视图中轻松渲染的组件。

缓存

内置对组件输出缓存的支持，以提升性能。

动态配置

通过配置文件定义和管理组件。

模块兼容性

完全兼容模块化应用，包括使用 nwidart/laravel-modules 的应用。

高级 Blade 指令

使用自定义 Blade 指令在任何视图位置渲染组件。

安装

步骤 1：安装包使用 Composer 安装包

composer require highvertical/widget-package

步骤 2：发布配置文件将包的配置文件发布到 Laravel 应用程序的配置目录

php artisan vendor:publish --tag=widget-config

此命令将在您的应用程序中创建一个 config/widgets.php 文件。

步骤 3：自动加载服务提供者（可选）如果您的应用程序不支持包自动发现，请在 config/app.php 中手动添加服务提供者

'providers' => [
    // Other Service Providers...

    Highvertical\WidgetPackage\Providers\WidgetServiceProvider::class,
],

基本使用

步骤 1：创建组件组件可以在应用程序的任何位置创建。以下是一个简单的天气组件示例

<?php

namespace App\Widgets;

use Highvertical\WidgetPackage\Widgets\Widget;

class WeatherWidget extends Widget
{
    public function render(array $params = [])
    {
        $location = $params['location'] ?? 'Unknown Location';

        // Mocked data, replace with real data fetching logic
        $weatherData = [
            'location' => $location,
            'temperature' => '25°C',
            'condition' => 'Sunny',
        ];

        return view('widgets.weather', compact('weatherData'));
    }
}

步骤 2：注册组件创建组件类后，在 config/widgets.php 文件中注册它

<?php

return [
    'widgets' => [
        'weather' => \App\Widgets\WeatherWidget::class,
    ],
    'cache' => [
        'enabled' => true,
        'ttl' => 60, // Cache time-to-live in minutes
    ],
];

步骤 3：在 Blade 视图中使用组件您现在可以使用自定义的 @widget 指令在任何 Blade 视图中使用您的组件

@widget('weather', ['location' => 'New York'])

高级使用

缓存

Widget Package 默认支持缓存。要启用缓存，只需确保在 config/widgets.php 文件中将 cache.enabled 配置设置为 true

'cache' => [
    'enabled' => true,
    'ttl' => 60, // Cache time-to-live in minutes
],

启用缓存时，组件输出将存储并在指定的时间生存期内重用。

动态组件配置

组件可以在应用程序的不同部分动态定义，包括在模块化应用中。这使代码更加灵活和易于维护，特别是在大型项目中。

示例：使用 nwidart/laravel-modules 的模块化组件

如果您使用 nwidart/laravel-modules，您可以在各个模块内定义组件。例如，在一个名为 Blog 的模块中，创建一个 Config/widgets.php 文件

<?php

return [
    'widgets' => [
        'recentPosts' => \Modules\Blog\Widgets\RecentPostsWidget::class,
    ],
];

包将自动检测并注册这些组件，使它们在整个应用程序中可用。

处理组件依赖关系

组件可能需要由 Laravel 服务容器解析的依赖项。您可以通过在组件类中定义构造函数来轻松注入这些依赖项

<?php

namespace App\Widgets;

use App\Services\WeatherService;
use Highvertical\WidgetPackage\Widgets\Widget;

class WeatherWidget extends Widget
{
    protected $weatherService;

    public function __construct(WeatherService $weatherService)
    {
        $this->weatherService = $weatherService;
    }

    public function render(array $params = [])
    {
        $location = $params['location'] ?? 'Unknown Location';
        $weatherData = $this->weatherService->getWeather($location);

        return view('widgets.weather', compact('weatherData'));
    }
}

扩展和覆盖配置

要扩展或覆盖默认组件配置，请修改 config/widgets.php 文件。如果您将包集成到现有项目中并需要根据特定需求进行适配，这尤其有用。

Blade 指令

包注册了一个自定义的 Blade 指令 @widget，使得在视图中渲染组件变得简单。此指令接受组件别名和一个可选的参数数组。

@widget('weather', ['location' => 'San Francisco'])

示例组件

示例 1：最新文章组件

<?php

namespace Modules\Blog\Widgets;

use Highvertical\WidgetPackage\Widgets\Widget;
use Modules\Blog\Repositories\PostRepository;

class RecentPostsWidget extends Widget
{
    protected $postRepository;

    public function __construct(PostRepository $postRepository)
    {
        $this->postRepository = $postRepository;
    }

    public function render(array $params = [])
    {
        $posts = $this->postRepository->getRecentPosts($params['limit'] ?? 5);

        return view('blog::widgets.recent-posts', compact('posts'));
    }
}

示例 2：用户资料组件

<?php

namespace App\Widgets;

use Highvertical\WidgetPackage\Widgets\Widget;
use App\Models\User;

class UserProfileWidget extends Widget
{
    public function render(array $params = [])
    {
        $user = User::find($params['user_id']);

        return view('widgets.user-profile', compact('user'));
    }
}

定制和扩展性

Widget Package 被设计为易于定制和扩展。您可以创建自己的组件、定制现有组件，甚至扩展包的核心功能以满足特定需求。

贡献

我们欢迎对Widget包的贡献。如果您有改进的想法，发现了一个错误，或者想帮助编写文档，请随意提交一个pull请求或在GitHub上创建一个issue。

许可证

Widget包是开源软件，使用MIT许可证授权。

highvertical / widget-package

维护者

详情