后端列表

• Introduction
• 配置列表行为
  • 添加工具栏
  • 筛选列表
• 定义列表列
  • 列选项
  • 自定义值选择
  • 嵌套列选择
• 可用的列类型
• 显示列表
• 多个列表定义
• 使用列表过滤器
  • 范围选项
  • 过滤依赖
  • 可用范围类型
• 扩展列表行为
  • 覆盖控制器动作
  • 覆盖视图
  • 扩展列定义
  • 注入 CSS 行类
  • 扩展过滤范围
  • 扩展模型查询
  • 扩展记录收集
  • 自定义列类型

#Introduction

这列表行为 是控制器behavior 用于管理页面上的记录列表。该行为为可排序和可搜索列表提供了每个记录的可选链接。行为提供控制器动作index;然而，列表可以在任何地方呈现，并且可以使用多个列表定义。

列表行为取决于列表列定义 和一个模型类.为了使用列表行为，您应该添加\Backend\Behaviors\ListController::class 的定义$implement 控制器类的属性。

namespace Acme\Blog\Controllers;

class Categories extends \Backend\Classes\Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\ListController::class,
    ];
}

NOTE: 很多时候列表和形成行为 在同一个控制器中一起使用。

#配置列表行为

List 行为将从一个 YAML 格式加载其配置config_list.yaml 文件位于控制器的查看目录 (plugins/myauthor/myplugin/controllers/mycontroller/config_list.yaml） 默认情况下。

这可以通过覆盖$listConfig 控制器上的属性以引用不同的文件名或完整的配置数组：

public $listConfig = 'my_custom_list_config.yaml';

下面是一个典型的列表行为配置文件的例子：

# ===================================
#  List Behavior Config
# ===================================

title: Blog Posts
list: ~/plugins/acme/blog/models/post/columns.yaml
modelClass: Acme\Blog\Models\Post
recordUrl: acme/blog/posts/update/:id

列表配置文件中需要以下字段：

下面列出的配置选项是可选的。

#添加工具栏

要在列表中包含工具栏，请将以下配置添加到列表配置 YAML 文件中：

toolbar:
    buttons: list_toolbar
    search:
        prompt: Find records

工具栏配置允许：

搜索配置支持以下选项：

上面提到的部分工具栏按钮应该包含带有一些按钮的工具栏控件定义。部分还可以包含记分牌控制 与图表。部分工具栏示例最新帖子 按钮指的是create 提供的行动形式行为:

<div data-control="toolbar">
    <a
        href="<?= Backend::url('acme/blog/posts/create') ?>"
        class="btn btn-primary wn-icon-plus">New Post</a>
</div>

#筛选列表

要按用户定义的输入过滤列表，请将以下列表配置添加到 YAML 文件中：

filter: config_filter.yaml

这filter 选项应参考过滤器配置文件 路径或提供一个带有配置的数组。

#定义列表列

列表列是使用 YAML 文件定义的。列表行为使用列配置来创建记录表并在表单元格中显示模型列。该文件被放置到的子目录models 一个插件的目录。子目录名称与小写的模型类名称匹配。文件名无关紧要，但columns.yaml 和list_columns.yaml 是常见的名字。示例列表列文件位置：

📂 plugins
 ┗ 📂 acme
   ┗ 📂 blog
     ┗ 📂 models                   <=== Plugin models directory
       ┣ 📂 post                   <=== Model configuration directory
       ┃ ┗ 📜 list_columns.yaml    <=== Model list columns config file
       ┗ 📜 Post.php               <=== model class

下一个示例显示列表列定义文件的典型内容。

# ===================================
#  List Column Definitions
# ===================================

columns:
    name: Name
    email: Email

#列选项

对于每一列都可以指定这些选项（如果适用）：

#自定义值选择

可以更改每一列的来源和显示值。如果您想从另一个模型属性（甚至是关系的属性）获取实际显示的列值，您可以使用valueFrom 选项。

other_name:
    label: Something Great
    valueFrom: name

#嵌套列选择

在某些情况下，从嵌套数据结构中检索列值是有意义的，例如模型关系 专栏或jsonable数组.这样做的唯一缺点是无法将列标记为可搜索或可排序，因为这些选项要求该列实际存在于数据库表中。

content[title]:
    name: Title
    sortable: false

上面的例子会在 PHP 中寻找等价于$record->content->title 或者$record->content['title'] 分别。如果您需要使列可搜索或可排序，您可以使用模型事件 每当嵌套值发生变化时，将其本地复制到真实的数据库表列中。

#可用的列类型

有多种列类型可用于type 设置，这些控制列表列的显示方式。除了下面指定的本机列类型之外，您还可以定义自定义列类型.

#Text

text - 显示文本列，左对齐

full_name:
    label: Full Name
    type: text

您还可以指定自定义文本格式，例如管理员：全名（有效）

full_name:
    label: Full Name
    type: text
    format: Admin:%s (active)

#Image

image - 使用内置的显示图像图像调整功能.

avatar:
    label: Avatar
    type: image
    sortable: false
    width: 150
    height: 150
    default: '/modules/backend/assets/images/logo.svg'
    options:
        quality: 80

见图像调整文档 有关支持哪些图像源以及什么的更多信息options 支持

#Number

number - 显示数字列，右对齐

age:
    label: Age
    type: number

您还可以指定自定义数字格式，例如货币$ 99.00

price:
    label: Price
    type: number
    format: $ %.2f

NOTE: 两个都text 和number 列支持format 属性，此属性遵循PHP sprintf() 函数.值必须是字符串。

#Switch

switch - 显示布尔列的开或关状态。

enabled:
    label: Enabled
    type: switch

#约会时间

datetime - 将列值显示为格式化的日期和时间。下一个示例将日期显示为1975 年 12 月 25 日星期四下午 2:15.

created_at:
    label: Date
    type: datetime

您还可以指定自定义日期格式，例如1975 年 12 月 25 日星期四下午 02:15:16:

created_at:
    label: Date
    type: datetime
    format: l jS \of F Y h:i:s A

您可能还希望设置ignoreTimezone: true 以防止显示的日期和数据库中存储的日期之间的时区转换，因为默认情况下后端时区首选项应用于显示值。

created_at:
    label: Date
    type: datetime
    ignoreTimezone: true

NOTE: 这ignoreTimezone 选项也适用于其他日期和时间相关的字段类型，包括date,time,timesince 和timetense.

#Date

date - 将列值显示为日期格式j, Y

created_at:
    label: Date
    type: date

#Time

time - 将列值显示为时间格式g:我一个

created_at:
    label: Date
    type: time

#时间自

timesince - 显示从值到当前时间的人类可读时间差。例如：10 分钟前

created_at:
    label: Date
    type: timesince

#时态

timetense - 使用当前日期的语法时态显示 24 小时制时间和日期。例如：今天 12:49,昨天 4:00 或者2015 年 9 月 18 日 14:33.

created_at:
    label: Date
    type: timetense

#Select

select - 允许使用自定义选择语句创建列。任何有效的 SQL SELECT 语句都适用于此。

full_name:
    label: Full Name
    select: concat(first_name, ' ', last_name)

#Relation

relation - 允许显示相关列，你可以提供一个关系选项。此选项的值必须是 Active Record 的名称relationship 在你的模型上。在下一个例子中name 值将被转换为在相关模型中找到的名称属性（例如：$model->name).

group:
    label: Group
    relation: groups
    select: name

应用条件可以使用conditions 财产。给定以下结构：

Entries:
- id
- created_at

EntryData:
- entry_id
- key
- value

您可以使用以下配置将单个 EntryData 记录显示为列表小部件中的单独列：

id:
    label: ID
created_at:
    label: Created at
_entry_field_email:
    label: Email
    relation: entry_data
    select: value
    conditions: "`key` = 'email'"

要显示显示相关记录数的列，请使用useRelationCount 选项。

users_count:
    label: Users
    relation: users
    useRelationCount: true

NOTE: 使用relation 列上的选项将从select将列编辑到此列指定的属性中。建议您在不与现有模型属性冲突的情况下命名显示关系数据的列，如下例所示：

最佳实践：

group_name:
    label: Group
    relation: group
    select: name

不良做法：

# This will overwrite the value of $record->group_id which will break accessing relations from the list view
group_id:
    label: Group
    relation: group
    select: name

#Partial

partial - 呈现部分，path value 可以引用部分视图文件，否则列名将用作部分名称。在部分内部，这些变量可用：$value 是默认的单元格值，$record 是用于细胞的模型和$column 是配置的类对象Backend\Classes\ListColumn.

content:
    label: Content
    type: partial
    path: ~/plugins/acme/blog/models/comment/_content_column.htm

#选色器

colorpicker - 显示颜色选择器列中的颜色

color:
    label: Background
    type: colorpicker

#显示列表

通常列表显示在索引中view 文件。由于列表包含工具栏，因此视图文件将仅包含单个listRender 方法调用。

<?= $this->listRender() ?>

#多个列表定义

列表行为可以使用命名定义支持同一控制器中的多个列表。这$listConfig 属性可以定义为一个数组，其中键是定义名称，值是配置文件。

public $listConfig = [
    'templates' => 'config_templates_list.yaml',
    'layouts' => 'config_layouts_list.yaml'
];

然后可以通过在调用时将定义名称作为第一个参数传递来显示每个定义listRender 方法：

<?= $this->listRender('templates') ?>

#使用列表过滤器

列表可以过滤添加过滤器定义 到列表配置。类似地，过滤器由它们自己的包含过滤器范围的配置文件驱动，每个范围都是可以过滤列表的一个方面。下一个示例显示过滤器定义文件的典型内容。

# ===================================
# Filter Scope Definitions
# ===================================

scopes:

    category:
        label: Category
        modelClass: Acme\Blog\Models\Category
        conditions: category_id in (:filtered)
        nameFrom: name

    status:
        label: Status
        type: group
        conditions: status in (:filtered)
        options:
            pending: Pending
            active: Active
            closed: Closed

    published:
        label: Hide published
        type: checkbox
        default: 1
        conditions: is_published <> true

    approved:
        label: Approved
        type: switch
        default: 2
        conditions:
            - is_approved <> true
            - is_approved = true

    created_at:
        label: Date
        type: date
        conditions: created_at >= ':filtered'

    published_at:
        label: Date
        type: daterange
        conditions: created_at >= ':after' AND created_at <= ':before'

#范围选项

对于每个范围，您可以指定这些选项（如果适用）：

#过滤依赖

过滤器作用域可以通过定义dependsOn 范围选项，它提供了一个服务器端解决方案，用于在修改其依赖项时更新范围。当声明为依赖项的范围发生变化时，定义范围将动态更新。这提供了更改要提供给范围的可用选项的机会。

country:
    label: Country
    type: group
    conditions: country_id in (:filtered)
    modelClass: Winter\Test\Models\Location
    options: getCountryOptions

city:
    label: City
    type: group
    conditions: city_id in (:filtered)
    modelClass: Winter\Test\Models\Location
    options: getCityOptions
    dependsOn: country

在上面的例子中，city 范围将刷新时country 范围发生了变化。定义的任何范围dependsOn 属性将传递给 Filter 小部件的所有当前范围对象，包括它们的当前值，作为以范围名称为键的数组。

public function getCountryOptions()
{
    return Country::lists('name', 'id');
}

public function getCityOptions($scopes = null)
{
    if (!empty($scopes['country']->value)) {
        return City::whereIn('country_id', array_keys($scopes['country']->value))->lists('name', 'id');
    } else {
        return City::lists('name', 'id');
    }
}

NOTE: 只有范围依赖关系type: group 在这一点上得到支持。

#可用范围类型

这些类型可用于确定过滤器范围的显示方式。

#Group

group - 按一组项目过滤列表，通常按相关模型，并且需要nameFrom 或者options 定义。例如：状态名称如打开、关闭等。

status:
    label: Status
    type: group
    conditions: status in (:filtered)
    default:
        pending: Pending
        active: Active
    options:
        pending: Pending
        active: Active
        closed: Closed

#Checkbox

checkbox - 用作二进制复选框以将预定义条件或查询应用于列表，打开或关闭。使用 0 表示关闭，1 表示默认值

published:
    label: Hide published
    type: checkbox
    default: 1
    conditions: is_published <> true

#Switch

switch - 用作在两个预定义条件或列表查询之间切换的开关，不确定、打开或关闭。使用 0 表示关闭，1 表示不确定，2 表示默认值

approved:
    label: Approved
    type: switch
    default: 1
    conditions:
        - is_approved <> true
        - is_approved = true

#Date

date - 显示要选择的单个日期的日期选择器。条件属性中可用的值是：

• :filtered: 所选日期格式为Y-m-d
• :before: 所选日期格式为Y-m-d 00:00:00, 从后端时区转换为应用程序时区
• :after: 所选日期格式为Y-m-d 23:59:59, 从后端时区转换为应用程序时区

created_at:
    label: Date
    type: date
    minDate: '2001-01-23'
    maxDate: '2030-10-13'
    yearRange: 10
    conditions: created_at >= ':filtered'

#日期范围

daterange - 显示一个日期选择器，用于选择两个日期作为日期范围。条件属性中可用的值是：

• :before：选定的“之前”日期格式为Y-m-d H:i:s
• :beforeDate：选定的“之前”日期格式为Y-m-d
• :after：选定的“之后”日期格式为Y-m-d H:i:s
• :afterDate：选定的“之后”日期格式为Y-m-d

published_at:
    label: Date
    type: daterange
    minDate: '2001-01-23'
    maxDate: '2030-10-13'
    yearRange: 10
    conditions: created_at >= ':after' AND created_at <= ':before'

为日期和日期范围使用默认值

myController::extendListFilterScopes(function($filter)
{
    $filter->addScopes([
        'Date Test' => [
            'label' => 'Date Test',
            'type' => 'daterange',
            'default' => $this->myDefaultTime(),
            'conditions' => "created_at >= ':after' AND created_at <= ':before'"
        ],
    ]);
});

// return value must be instance of carbon
public function myDefaultTime()
{
    return [
        0 => Carbon::parse('2012-02-02'),
        1 => Carbon::parse('2012-04-02'),
    ];
}

您可能还希望设置ignoreTimezone: true 以防止显示的日期和数据库中存储的日期之间的时区转换，因为默认情况下后端时区首选项应用于显示值。

published_at:
    label: Date
    type: daterange
    minDate: '2001-01-23'
    maxDate: '2030-10-13'
    yearRange: 10
    conditions: created_at >= ':after' AND created_at <= ':before'
    ignoreTimezone: true

NOTE: 这ignoreTimezone 选项也适用于date 过滤器类型也是如此。

#Number

number - 显示要输入的单个数字的输入。该值可在条件属性中用作:filtered.

这min 和max 选项指定用户可以输入的最小值和最大值。这step选项指定使用向上和向下箭头调整值时使用的步进间隔。

age:
    label: Age
    type: number
    default: 14
    step: 1
    min: 0
    max: 1000
    conditions: age >= ':filtered'

NOTE: 这step,min， 和max 选项也适用于numberrange 过滤器类型也是如此。

#号码范围

numberrange - 显示两个数字的输入作为数字范围输入。条件属性中可用的值是：

• :min: 最小值，默认为-2147483647
• :max: 最大值，默认为2147483647

您可以将最小值留空以搜索最大值之前的所有内容，反之亦然，您可以将最大值留空以搜索至少最小值的所有内容。

visitors:
    label: Visitor Count
    type: numberrange
    default:
        0: 10
        1: 20
    conditions: visitors >= ':min' and visitors <= ':max'

#Text

text - 显示要输入的字符串的文本输入。您可以指定一个size 将在输入大小属性中注入的属性（默认值：10）。

username:
    label: Username
    type: text
    conditions: username = :value
    size: 2

#扩展列表行为

有时您可能希望修改默认列表行为，有多种方法可以做到这一点。

• 覆盖控制器动作
• 覆盖视图
• 扩展列定义
• 注入 CSS 行类
• 扩展过滤范围
• 扩展模型查询
• 自定义列类型

#覆盖控制器动作

您可以使用自己的逻辑index 控制器中的 action 方法，然后可选地调用 List 行为index 父方法。

public function index()
{
    //
    // Do any custom code here
    //

    // Call the ListController behavior index() method
    $this->asExtension('ListController')->index();
}

#覆盖视图

这ListController behavior 有一个主容器视图，您可以通过创建一个名为_list_container.htm 在你的控制器目录中。以下示例将向列表添加侧边栏：

<?php if ($toolbar): ?>
    <?= $toolbar->render() ?>
<?php endif ?>

<?php if ($filter): ?>
    <?= $filter->render() ?>
<?php endif ?>

<div class="row row-flush">
    <div class="col-sm-3">
        [Insert sidebar here]
    </div>
    <div class="col-sm-9 list-with-sidebar">
        <?= $list->render() ?>
    </div>
</div>

该行为将调用一个Lists 还包含许多您可以覆盖的视图的小部件。这可以通过指定一个customViewPath 中描述的选项列出配置选项.小部件将首先在此路径中查找视图，然后返回到默认位置。

# Custom view path
customViewPath: $/acme/blog/controllers/reviews/list

NOTE: 使用子目录是个好主意，例如list, 避免冲突。

例如，要修改列表正文行标记，创建一个名为list/_list_body_row.htm 在你的控制器目录中。

<tr>
    <?php foreach ($columns as $key => $column): ?>
        <td><?= $this->getColumnValue($record, $column) ?></td>
    <?php endforeach ?>
</tr>

#扩展列定义

您可以通过调用从外部扩展另一个控制器的列extendListColumns 控制器类上的静态方法。这个方法可以有两个参数，$list 将代表列表小部件对象和$model 表示列表使用的模型。以这个控制器为例：

class Categories extends \Backend\Classes\Controller
{
    /**
     * @var array List of behaviors implemented by this controller
     */
    public $implement = [
        \Backend\Behaviors\ListController::class,
    ];
}

使用extendListColumns 方法，您可以向此控制器呈现的任何列表添加额外的列。最好检查一下$model 是正确的类型。这是一个例子：

Categories::extendListColumns(function($list, $model)
{
    if (!$model instanceof MyModel) {
        return;
    }

    $list->addColumns([
        'my_column' => [
            'label' => 'My Column'
        ]
    ]);

});

您还可以通过覆盖listExtendColumns 控制器类中的方法。

class Categories extends \Backend\Classes\Controller
{
    [...]

    public function listExtendColumns($list)
    {
        $list->addColumns([...]);
    }
}

$list 对象可以使用以下方法。

每个方法都采用类似于列表列配置.

#注入 CSS 行类

您可以通过添加一个自定义 css 行类来注入listInjectRowClass 控制器类上的方法。这个方法可以有两个参数，$record 将代表一个单一的模型记录和$definition 包含列表小部件定义的名称。您可以返回包含行类的任何字符串值。这些类将添加到该行的 HTML 标记中。

class Lessons extends \Backend\Classes\Controller
{
    [...]

    public function listInjectRowClass($lesson, $definition)
    {
        // Strike through past lessons
        if ($lesson->lesson_date->lt(Carbon::today())) {
            return 'strike';
        }
    }
}

一个特殊的 CSS 类nolink 可用于强制一行不可点击，即使recordUrl 或者recordOnClick 选项是为列表小部件定义的。在事件中返回此类将允许您使记录不可点击 - 例如，对于软删除行或信息行：

public function listInjectRowClass($record, $value)
{
    if ($record->trashed()) {
        return 'nolink';
    }
}

#扩展过滤范围

您可以通过调用从外部扩展另一个控制器的过滤器范围extendListFilterScopes 控制器类上的静态方法。这个方法可以接受参数$filter 它将代表 Filter 小部件对象。以这个控制器为例：

Categories::extendListFilterScopes(function($filter) {
    // Add custom CSS classes to the Filter widget itself
    $filter->cssClasses = array_merge($filter->cssClasses, ['my', 'array', 'of', 'classes']);

    $filter->addScopes([
        'my_scope' => [
            'label' => 'My Filter Scope'
        ]
    ]);
});

提供的范围数组类似于列表过滤器配置.

您还可以在内部将过滤器范围扩展到控制器类，只需覆盖listFilterExtendScopes 方法。

class Categories extends \Backend\Classes\Controller
{
    [...]

    public function listFilterExtendScopes($filter)
    {
        $filter->addScopes([...]);
    }
}

$filter 对象可以使用以下方法。

#扩展模型查询

列表的查找查询数据库模型 可以通过重写来扩展listExtendQuery 控制器类中的方法。此示例将确保软删除记录包含在列表数据中，方法是应用withTrashed查询范围：

public function listExtendQuery($query)
{
    $query->withTrashed();
}

在同一个控制器中处理多个列表定义时，可以使用的第二个参数listExtendQuery 其中包含定义的名称：

public $listConfig = [
    'inbox' => 'config_inbox_list.yaml',
    'trashed' => 'config_trashed_list.yaml'
];

public function listExtendQuery($query, $definition)
{
    if ($definition === 'trashed') {
        $query->onlyTrashed();
    }
}

这列表过滤器 模型查询也可以通过重写来扩展listFilterExtendQuery 方法：

public function listFilterExtendQuery($query, $scope)
{
    if ($scope->scopeName == 'status') {
        $query->where('status', '<>', 'all');
    }
}

NOTE: 为了应用limit() 您必须禁用查询的默认分页行为ListController 以防止它覆盖对查询的任何更改LIMIT.这可以通过设置来完成recordsPerPage: 0 在您的列表定义配置中。

#扩展记录收集

列表使用的记录集合可以通过覆盖listExtendRecords 控制器类中的方法。这个例子使用sort 上的方法唱片收藏 更改记录的排序顺序。

public function listExtendRecords($records)
{
    return $records->sort(function ($a, $b) {
        return $a->computedVal() > $b->computedVal();
    });
}

#自定义列类型

自定义列表列类型可以在后端注册registerListColumnTypes 的方法插件注册类.该方法应返回一个数组，其中键是类型名称，值是可调用函数。可调用函数接收三个参数，本机$value， 这$column 定义对象和模型$record 目的。

public function registerListColumnTypes()
{
    return [
        // A local method, i.e $this->evalUppercaseListColumn()
        'uppercase' => [$this, 'evalUppercaseListColumn'],

        // Using an inline closure
        'loveit' => function($value) { return 'I love '. $value; }
    ];
}

public function evalUppercaseListColumn($value, $column, $record)
{
    return strtoupper($value);
}

使用自定义列表列类型就像使用名称调用它一样简单type 选项。

# ===================================
#  List Column Definitions
# ===================================

columns:
    secret_code:
        label: Secret code
        type: uppercase