README

Netflex SDK 的 datatables Livewire 组件。

此插件假设您已经将 Laravel Livewire 安装并配置到您的项目中。

安装

您可以通过 composer 安装此包

composer require netflex/livewire-tables

发布资产

发布资产是可选的，除非您想自定义此包。

php artisan vendor:publish --provider="Netflex\Livewire\Tables\LivewireTablesServiceProvider" --tag=views

php artisan vendor:publish --provider="Netflex\Livewire\Tables\LivewireTablesServiceProvider" --tag=lang

用法

创建表格

要创建一个表格组件，您可以参考以下示例

<?php

namespace App\Http\Livewire;

use App\Article;
use Netflex\Query\Builder;

use Netflex\Livewire\Tables\TableComponent;
use Netflex\Livewire\Tables\Traits\HtmlComponents;
use Netflex\Livewire\Tables\Views\Column;

class ArticleTable extends TableComponent
{
    use HtmlComponents;

    public function query() : Builder
    {
        return Article::query()->ignorePublishingStatus();
    }

    public function columns() : array
    {
        return [
            Column::make('ID')
                ->searchable()
                ->sortable(),
            Column::make('Image')
                ->format(function(Article $article) {
                    return $this->image($article->image, 'tableArticlePreset', $article->name, ['class' => 'img-fluid']);
                }),
            Column::make('Name')
                ->searchable()
                ->sortable(),
            Column::make('E-mail', 'email')
                ->searchable()
                ->sortable()
                ->format(function(Article $article) {
                    return $this->mailto($article->email, null, ['target' => '_blank']);
                }),
            Column::make('Actions')
                ->format(function(Article $article) {
                    return view('backend.auth.user.includes.actions', ['article' => $article]);
                })
                ->hideIf(!auth()->user()),
        ];
    }
}

您的组件必须实现两个方法

/**
 * This defines the start of the query, usually Model::query() but can add additonal constraints to the query.
 */
public function query() : Builder;

/**
 * This defines the columns of the table, they don't necessarily have to map to fields in the model structure.
 */
public function columns() : array;

渲染表格

将以下内容放置在您想要表格出现的位置。

Netflex SDK 3.x

<livewire:article-table />

定义列

您可以使用列类来定义表格的列。

以下方法可以链接到列上

/**
 * The first argument is the column header text
 * The attribute can be omitted if the text is equal to the lower case snake_cased version of the column
 * The attribute can also be used to reference a relationship (i.e. role.name)
 */
public function make($text, ?$attribute) : Column;

/**
 * Used to format the column data in different ways, see the HTML Components section.
 * You will be passed the current model and column (if you need it for some reason) which can be omitted as an argument if you don't need it.
 */
public function format(callable $callable = null) : self;

/**
 * This column is searchable, with no callback it will search the column by name or by the supplied relationship, using a callback overrides the default searching functionality.
 */
public function searchable(callable $callable = null) : self;

/**
 * This column is sortable, with no callback it will sort the column by name and sort order defined on the components $sortDirection variable
 */
public function sortable(callable $callable = null) : self;

/**
 * The columns output will be put through {!! !!} instead of {{ }}.
 */
public function raw() : self;

/**
 * Hide this column permanently
 */
public function hide() : self;

/**
 * Hide this column based on a condition. i.e.: user has or doesn't have a role or permission. Must return a boolean, not a closure.
 */
public function hideIf($condition) : self;

/**
 * This column is only included in exports and is not available to the UI
 */
public function exportOnly() : self;

/**
 * This column is excluded from the export but visible to the UI unless defined otherwise with hide() or hideIf()
 */
public function excludeFromExport() : self;

/**
 * If supplied, and the column is exportable, this will be the format when rendering the CSV/XLS/PDF instead of the format() function. You may have both, format() for the UI, and exportFormat() for the export only. If this method is not supplied, format() will be used and passed through strip_tags() to try to clean the output.
 */
public function exportFormat(callable $callable = null) : self;

属性

您可以在表格组件中覆盖这些中的任何一个

表格

搜索

排序

分页

加载

离线

导出

其他

列/数据

使用以下方法来修改列/行元数据。

public function setTableHeadClass($attribute): ?string
public function setTableHeadId($attribute): ?string
public function setTableHeadAttributes($attribute): array
public function setTableRowClass($article): ?string
public function setTableRowId($article): ?string
public function setTableRowAttributes($article): array
public function getTableRowUrl($article): ?string
public function setTableDataClass($attribute, $value): ?string
public function setTableDataId($attribute, $value): ?string
public function setTableDataAttributes($attribute, $value): array

分页

如果要在搜索或每页属性更改时执行额外任务，请覆盖这些方法。

public function updatingSearch(): void
public function updatingPerPage(): void

搜索

如果要在搜索已清除时执行额外步骤，请覆盖此方法。

public function clearSearch(): void

排序

如果想要更改默认排序行为，请覆盖此方法。

public function sort($attribute): void

HTML 组件

此包包括来自 laravelcollective/html 包的一些功能，已修改以适应本包的需求。

要使用这些功能，您必须导入 Netflex\Livewire\Tables\Traits\HtmlComponents trait。

您可以从列的 format() 方法返回这些函数中的任何一个

public function image($pathOrMediaUrlResolvable, $presetOrSize, $alt = null, $attributes = []): HtmlString
public function link($url, $title = null, $attributes = [], $secure = null, $escape = true): HtmlString
public function secureLink($url, $title = null, $attributes = [], $escape = true): HtmlString
public function linkAsset($url, $title = null, $attributes = [], $secure = null, $escape = true): HtmlString
public function linkSecureAsset($url, $title = null, $attributes = [], $escape = true): HtmlString
public function linkRoute($name, $title = null, $parameters = [], $attributes = [], $secure = null, $escape = true): HtmlString
public function linkAction($action, $title = null, $parameters = [], $attributes = [], $secure = null, $escape = true): HtmlString
public function mailto($email, $title = null, $attributes = [], $escape = true): HtmlString
public function email($email): string
public function html($html): HtmlString

数据导出

表格组件支持导出到 CSV、XLS、XLSX 和 PDF。

为了使用此功能，您必须安装 PhpSpreadsheet 1.0 或更高版本。

您的表格支持哪些导出

默认情况下，导出是关闭的。您可以使用 $exports 类属性添加可用导出类型的列表。

public $exports = ['csv', 'xls', 'xlsx', 'pdf'];

定义文件名。

默认情况下，文件名将是 data.type。例如，data.pdf、data.csv。

您可以使用 $exportFileName 类属性更改文件名。

public $exportFileName = 'users-table'; - 显然省略文件类型

决定要导出的列

您在导出信息上有几种选择。默认情况下，如果没有定义，所有列都将导出。

如果您有一个希望对 UI 可见但不对导出可见的列，可以在 excludeFromExport() 上链式调用

如果您有一个希望对导出可见但对 UI 不可见的列，可以在 exportOnly() 上链式调用

格式化导出列数据

默认情况下，导出会尝试将信息以与UI显示相同的方式渲染。对于基于列的正常属性来说，这很好，但当导出格式化列并输出视图或HTML时，它会尝试删除HTML。

相反，您可以使用列上的exportFormat()方法来定义您希望该列在输出到文件时如何格式化。

因此，您可以有一个既希望对UI和导出都可用，又可以根据输出位置不同而格式不同的列。

导出示例

<?php

namespace App\Http\Livewire;

use App\Article;

use Netflex\Query\Builder;
use Netflex\Livewire\Tables\TableComponent;
use Netflex\Livewire\Tables\Traits\HtmlComponents;
use Netflex\Livewire\Tables\Views\Column;

class ArticleTable extends TableComponent
{
    use HtmlComponents;

    public function query() : Builder
    {
        return Article::query()->ignorePublishingStatus();
    }

    public function columns() : array
    {
        return [
            Column::make('ID')
                ->searchable()
                ->sortable()
                ->excludeFromExport(), // This column is visible to the UI, but not export.
            Column::make('ID')
                ->exportOnly(), // This column is only rendered on export
            Column::make('Image')
                ->format(function(User $article) {
                    return $this->image($article->image, 'presetName', $article->name, ['class' => 'img-fluid']);
                })
                ->excludeFromExport(), // This column is visible to the UI, but not export.
            Column::make('Name') // This columns is visible to both the UI and export, and is rendered the same
                ->searchable()
                ->sortable(),
            Column::make('E-mail', 'email')
                ->searchable()
                ->sortable()
                ->format(function(Article $article) {
                    return $this->mailto($article->email, null, ['target' => '_blank']);
                })
                ->exportFormat(function(User $article) { // This column is visible to both the UI and the export, but is formatted differently to the export via this method.
                    return $article->email;
                }),
            Column::make('Actions')
                ->format(function(User $article) {
                    return view('backend.auth.user.includes.actions', ['article' => $article]);
                })
                ->hideIf(!auth()->user())
                ->excludeFromExport(), // This column is visible to the UI, but not export.
        ];
    }
}

定制导出

目前，没有可用的定制选项。但有一个名为exports的配置项，您可以在其中定义用于渲染的类。您可以使用\Netflex\Livewire\Tables\Exports\Export类作为基础。

未来将添加更多选项，但内置选项应该适用于大多数应用程序。

设置组件选项

有一些特定于前端框架的选项可以设置。

这些必须从您组件的$options属性中进行设置。

它们以这种方式设置，而不是通过配置文件，这样您可以对这些设置进行每个组件的控制。

protected $options = [
    // The class set on the table
    'classes.table' => 'table table-striped table-bordered',

    // The class set on the table's thead
    'classes.thead' => null,

    // The class set on the table's export dropdown button
    'classes.buttons.export' => 'btn btn-secondary',
    
    // Whether or not the table is wrapped in a `.container-fluid` or not
    'container' => true,
    
    // Whether or not the table is wrapped in a `.table-responsive` or not
    'responsive' => true,
];

为了使此功能正常工作，您必须将一个关联数组（包含覆盖值）传递给$options属性。上述内容是默认值，如果您没有更改它们，则可以省略或完全忽略该属性。

传递属性

要从blade视图传递属性到您的表格，您可以使用正常的Livewire mount方法。

<livewire:article-table status="{{ request('status') }}" />

protected $status = 'active';

public function mount($status) {
    $this->status = $status;
}

许可

版权所有 Apility AS © 2021

根据MIT许可证许可。

此软件包含基于laravel-livewire-tables包的工作：版权所有 © Anthony Rappa 和 贡献者