README

⚠️ 此包已弃用并不再维护。未建议任何替代包。⚠️

👉 如果您有兴趣成为此包的主要维护者，请与我联系！

Rinvex Widgets 是一个强大且易于使用的组件系统，它结合了代码逻辑的力量和模板视图的灵活性。您可以创建异步组件、可重载组件，并使用控制台生成器自动生成您的组件，一切尽在掌握之中。

安装

通过 composer 安装此包
```
composer require rinvex/laravel-widgets
```
完成！

使用

创建您的组件

假设我们想要创建一个最近文章列表的组件，并在多个位置重用它。

首先，我们可以使用以下命令创建一个组件类

php artisan make:widget RecentPosts

该命令将生成一个具有 App\Widgets\RecentPosts 命名空间的新组件类，默认位置在 app/Widgets/RecentPosts.php 路径。

组件的基本内容如下

<?php

namespace App\Widgets;

use Rinvex\Widgets\Models\AbstractWidget;

class RecentPosts extends AbstractWidget
{
    /**
     * Treat this method as a normal PHP method, or a controller action.
     * You may return view() or other content to render and display.
     */
    public function make()
    {
        //
    }
}

所有组件必须继承 Rinvex\Widgets\Models\AbstractWidget，并且必须有一个公共的 make 方法，您可以在该方法内部返回任何您想要的，有完全的自由和完全的灵活性来编写自己的逻辑并返回结果，无论是纯数据数组/json、渲染视图或其他内容。这完全取决于您。将此方法视为一个正常的 PHP 方法或控制器操作。您可能返回 view('view.path.here') 或其他要渲染和显示的内容。

调用您的组件

组件通过其完全限定的命名空间调用，例如，查看以下代码

$recentPosts = app('rinvex.widgets')->make('App\Widgets\RecentPosts');

现在您可以在视图的任何位置使用该 $recentPosts，它包含组件的结果。

为了方便起见，Rinvex Widgets 还包含一个组件助手，以便易于使用。示例

$recentPosts = widget('App\Widgets\RecentPosts');

您还可以使用相同的签名在视图中使用 blade 指令调用组件

@widget('App\Widgets\RecentPosts')

最后但同样重要的是，有一个自动注册到您的应用程序中的 Widget 门面，因此您也可以使用 Widget::make('App\Widgets\RecentPosts')。

Widget::make() 方法（以及类似的所有上述替代调用方法）接受三个参数；第一个参数是唯一的必需参数，即您要调用的组件的完全限定命名空间，第二个参数是传递给组件构造函数的可选参数，第三个参数是一个布尔标志，用于异步加载，稍后我们将讨论。

组件参数

如前所述，小部件创建需要三个参数；第一个参数是唯一的必选参数，即你正在调用的完全限定命名空间的小部件，第二个参数用于传递给小部件构造函数的可选参数，第三个参数是一个布尔标志，用于异步加载，可以是true或false。

$recentPosts = Widget::make('App\Widgets\RecentPosts', ['param1' => 'Value #1'], true);

正如你所看到的，这个小部件现在是以异步方式加载的，关于这个特性的更多内容稍后介绍。

异步小部件

在某些情况下，使用AJAX加载小部件内容可能会非常有益。

幸运的是，这可以非常容易地实现！你需要做的就是将true作为第三个参数传递给Widget Facade或blade指令。例如：Widget::make('Widget\Class\Path', [], true)，同样也可以用@widget('Widget\Class\Path', [], true)。

注意：在异步调用小部件时，参数在请求中是加密发送的，所以请确保在发送和接收之前都进行json_encoded和json_decoded。

默认情况下，异步调用完成之前不会显示任何内容。这可以通过在小部件类中添加一个placeholder()方法来自定义，并返回要显示的任何字符串。请看以下示例

public function placeholder()
{
    return 'Loading...';
}

注意

Rinvex Widgets 包会自动注册一个名为 rinvex.widgets.async 的新路由，该路由可以通过 http://yourproject.app/widget 访问。该路由接受异步小部件调用，带有必要参数，所有这些参数都是加密的，并对其进行处理然后返回响应。

如果你需要修改默认的路由定义或行为，你可能需要将 Rinvex\Widgets\Providers\WidgetsServiceProvider 复制到你的应用中，根据你的需要进行修改，并在Laravel应用程序中注册它而不是默认的一个。在这种情况下，你可能需要禁用 Laravel 自动发现对于此包 Rinvex Widgets。

可重载小部件

你可以更进一步，自动每N秒重载小部件。

只需设置小部件类的 $reloadTimeout 属性即可。

class RecentPosts extends AbstractWidget
{
    /**
     * The number of seconds before each reload.
     *
     * @var float
     */
    protected $reloadTimeout;
}

同步和异步小部件都可以成为可重载的。你应该小心使用这个特性，因为如果超时时间太低，它很容易让你的应用充满异步调用。

如果你需要短响应时间或实时性，你可能需要考虑使用WebSocket，在这种情况下它更好，但默认情况下此包不实现。

容器

异步和可重载小部件都需要一些DOM交互，因此它们将所有小部件输出包裹在一个HTML容器中。这个容器由 AbstractWidget::container() 方法定义，也可以自定义。

为了使其简单、灵活、可缓存、性能更好，并且可覆盖，我们使这个容器接受一个视图路径，因此你可以在该视图中使用任何你想要的语法，包括当然是非常可爱的blade标签和指令。

只需设置小部件类的 $container 属性即可。

class RecentPosts extends AbstractWidget
{
    /**
     * The widget container template.
     *
     * @var string
     */
    protected $container = 'rinvex/widgets::container';
}

注意：当前不支持嵌套异步和可重载小部件。

小部件组

在大多数情况下，Blade 是设置小部件位置和顺序的完美工具。然而，有时你可能发现从列的角度将小部件分组在一起处理很有用。请查看以下示例

// add several widgets to the 'sidebar' group
Widget::group('sidebar')->addWidget(Widget::make('App\Widgets\RecentPosts'), 10);
Widget::group('sidebar')->addWidget(Widget::make('App\Widgets\LatestVisitors'), 20);

Widget::addWidget() 方法接受两个参数，第一个参数是渲染的部件，它是一个 Illuminate\Support\HtmlString 实例，第二个参数是你想在组中放置该部件的位置。位置？！是的，正是这样。你可以在每个组内部对部件进行排序，你可以将部件组想象成CMS的列，这样你就可以按你想要的方式构建你的页面。

要渲染一个部件组并打印输出，你可以这样做

$sidebar = Widget::group('sidebar')->render();

或者使用blade语法

@widgetGroup('sidebar')

如果你想获取所有部件组的集合，可以按照以下方式操作

$groups = Widget::groups();

注意

Widget::group('sidebar') 返回一个部件集合，而 Widget::groups() 返回一个部件组集合。这两个集合都可以像使用 Laravel 集合一样使用。

你可以设置一个分隔符，该分隔符将在同一组内部部部件之间显示，如下所示

Widget::group('sidebar')->separateWith('<hr>');

你也可以使用 wrap 方法将每个部件包裹起来。

Widget::group('sidebar')->wrapCallback(function ($key, $widget) {
    return "<div class='widget-{$key}'>{$widget}</div>";
});

wrapCallback() 方法接受一个回调函数，该回调函数接受两个变量。第一个变量是部件在组中的索引/键，第二个变量是部件的渲染内容，作为 \Illuminate\Support\HtmlString 对象。请注意，你可以完全访问整个部件组集合，因此你可以查询部件的总数，例如 $this->count() 或你可能需要的任何其他信息。

检查部件组的状态

// Check if widget group is empty or not
Widget::group('sidebar')->isEmpty(); // bool

// Get widgets count in the widget group
Widget::group('sidebar')->count(); // int

同样，你也可以检查所有组的状态

// Check if there's any widget groups or not
Widget::groups()->isEmpty(); // bool

// Get widget groups count
Widget::groups()->count(); // int

注意

Widget 类是一个外观，它自动注册到你的Laravel应用中，所以你可以在任何地方调用它，甚至在控制器或视图中。你可以仅调用别名的外观为 Widget，或者调用完全限定的命名空间为 Rinvex\Widgets\Facades\Widget，没有区别。

Widget 外观具有流畅的API，这意味着你可以轻松地连锁调用方法。

变更日志

请参阅变更日志以获取项目的完整历史。

支持

以下支持渠道就在你的指尖

贡献 & 协议

感谢您考虑为此项目做出贡献！贡献指南可以在 CONTRIBUTING.md 中找到。

欢迎提交错误报告、功能请求和拉取请求。

安全漏洞

如果你在这个项目中发现了安全漏洞，请发送电子邮件到 help@rinvex.com。所有安全漏洞都将得到及时联系。

关于Rinvex

Rinvex是一家成立于2016年6月的开罗，埃及的软件解决方案初创公司，专门为中小企业提供集成企业解决方案。我们相信我们的动力是“价值、触达和影响”，这是我们区别于他人的地方，通过软件的力量释放我们哲学的无尽可能性。我们喜欢称之为“生活速度的创新”。这就是我们为推动人类进步做出贡献的方式。

许可证

本软件遵循 MIT 许可协议 (MIT) 发布。

rinvex / laravel-widgets

维护者

详细信息