# 后台列表
### 介绍
**列表行为**是控制器修改器，用于轻松地将记录列表添加到页面。该行为提供可排序和可搜索的列表，并在其记录上带有可选链接。该行为提供了控制器操作，`index`但是可以将列表呈现在任何位置，并且可以使用多个列表定义。
列表行为取决于列表[列定义](https://octobercms.com/docs/backend/lists#list-columns)和[模型类](https://octobercms.com/docs/database/model)。为了使用列表行为，您应该将其添加到`$implement`控制器类的属性中。另外，`$listConfig`应该定义class属性，并且其值应引用用于配置行为选项的YAML文件。
~~~
namespace Acme\Blog\Controllers;
class Categories extends \Backend\Classes\Controller
{
public $implement = ['Backend.Behaviors.ListController'];
public $listConfig = 'list_config.yaml';
}
~~~
> **注意：**通常，列表和[表单行为](https://octobercms.com/docs/backend/form)在同一控制器中一起使用。
### [](https://octobercms.com/docs/backend/lists#configuring-list)配置列表行为
`$listConfig`属性中引用的配置文件以YAML格式定义。该文件应放置在控制器的[views目录中](https://octobercms.com/docs/backend/controllers-ajax/#introduction)。下面是一个典型的列表行为配置文件的示例：
~~~
# ===================================
# 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
~~~
列表配置文件中必须包含以下字段：
| 领域 | 描述 |
| --- | --- |
| **title** | 此列表的标题。 |
| **list** | 配置数组或对列表列定义文件的引用，请参阅[列表列](https://octobercms.com/docs/backend/lists#list-columns)。 |
| **modelClass** | 一个模型类名，列表数据就是从这个模型加载的。 |
下面列出的配置选项是可选的。
| 选项 | 描述 |
| --- | --- |
| **filter** | 过滤器配置，请参阅[过滤列表](https://octobercms.com/docs/backend/lists#adding-filters)。 |
| **recordUrl** | 将每个列表记录链接到另一个页面。例如：**users / update：id**。该`:id`部分将替换为记录标识符。这使您可以链接列表行为和[表单行为](https://octobercms.com/docs/backend/forms)。 |
| **recordOnClick** | 单击记录时执行的自定义JavaScript代码。 |
| **noRecordsMessage** | 找不到记录时显示的消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **deleteMessage** | 批量删除记录时显示的消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **noRecordsDeletedMessage** | 触发批量删除操作但未删除任何记录时显示的消息，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **recordsPerPage** | 每页显示的记录，无页使用0。默认值：0 |
| **showPageNumbers** | 分页显示页码。禁用此选项可提高使用大型表时的列表性能。默认值：true |
| **toolbar** | 引用工具栏窗口小部件配置文件或具有配置的数组（请参见下文）。 |
| **showSorting** | 在每一列上显示排序链接。默认值：true |
| **defaultSort** | 未定义用户首选项时，设置默认的排序列和方向。支持带键`column`和的字符串或数组`direction`。 |
| **showCheckboxes** | 在每个记录旁边显示复选框。默认值：false。 |
| **showSetup** | 显示列表列设置按钮。默认值：false。 |
| **showTree** | 显示父/子记录的树层次结构。默认值：false。 |
| **showTree** | 默认情况下是否应扩展树节点。默认值：false。 |
| **customViewPath** | 指定一个自定义视图路径以覆盖列表使用的局部变量（可选）。 |
### [](https://octobercms.com/docs/backend/lists#adding-toolbar)添加工具栏
要将工具栏包含在列表中，请将以下配置添加到列表配置YAML文件中：
~~~
toolbar:
buttons: list_toolbar
search:
prompt: Find records
~~~
工具栏配置允许：
| 选项 | 描述 |
| --- | --- |
| **buttons** | 使用工具栏按钮对控制器部分文件的引用。例如：**\_list\_toolbar.htm** |
| **search** | 对搜索窗口小部件配置文件或具有配置的数组的引用。 |
搜索配置支持以下选项：
| 选项 | 描述 |
| --- | --- |
| **prompt** | 在没有活动搜索时显示的占位符，可以引用[本地化字符串](https://octobercms.com/docs/plugin/localization)。 |
| **mode** | 将搜索策略定义为包含所有单词，任何单词或确切短语。支持的选项：所有，任何，确切。默认值：全部。 |
| **scope** | 指定在**列表模型中**定义的[查询范围方法](https://octobercms.com/docs/database/model#query-scopes)以应用于搜索查询，第一个参数将包含搜索项。 |
| **searchOnEnter** | 将其设置为true将使搜索窗口小部件在开始搜索之前等待按下Enter键（默认行为是，它在有人在搜索字段中输入内容后自动开始搜索，然后暂停片刻）。默认值：false。 |
上面提到的部分工具栏按钮应包含带有某些按钮的工具栏控件定义。局部也可以包含带有图表的[记分板控件](https://octobercms.com/docs/backend/controls#scoreboards)。带有“**新帖子”**按钮的部分工具栏示例，它引用了[表单行为](https://octobercms.com/docs/backend/forms)提供的**创建**动作：[](https://octobercms.com/docs/backend/forms)
~~~
<div data-control="toolbar">
<a
href="<?= Backend::url('acme/blog/posts/create') ?>"
class="btn btn-primary oc-icon-plus">New Post</a>
</div>
~~~
### [](https://octobercms.com/docs/backend/lists#adding-filters)筛选清单
要通过用户定义的输入过滤列表，请将以下列表配置添加到YAML文件：
~~~
filter: config_filter.yaml
~~~
该**过滤器**选项应参照本发明的[过滤器配置文件](https://octobercms.com/docs/backend/lists#list-filters)路径或提供与该配置的阵列。
### [](https://octobercms.com/docs/backend/lists#list-columns)定义列表列
列表列是使用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
~~~
### [](https://octobercms.com/docs/backend/lists#column-options)列选项
对于每一列，可以指定以下选项（如果适用）：
| 选项 | 描述 |
| --- | --- |
| **label** | 向用户显示列表列时的名称。 |
| **type** | 定义应如何呈现此列（请参见下面的[列类型](https://octobercms.com/docs/backend/lists#column-types)）。 |
| **default** | 如果值为空，则指定列的默认值。 |
| **searchable** | 在列表搜索结果中包括此列。默认值：false。 |
| **invisible** | 指定默认情况下是否隐藏此列。默认值：false。 |
| **sortable** | 指定是否可以对该列进行排序。默认值：true。 |
| **clickable** | 如果设置为false，则在单击列时禁用默认的单击行为。默认值：true。 |
| **select** | 定义用于该值的定制SQL select语句。 |
| **valueFrom** | 定义要用于值的模型属性。 |
| **relation** | 定义模型关系列。 |
| **useRelationCount** | 使用定义的计数`relation`作为此列的值。默认值：false |
| **cssClass** | 将CSS类分配给列容器。 |
| **headCssClass** | 将CSS类分配给列标题容器。 |
| **width** | 设置列宽，可以以百分比（10％）或像素（50px）的形式指定。可能只有一列未指定宽度，它将被拉伸以占用可用空间。 |
| **align** | 指定列对齐方式。可能的值是`left`，`right`和`center`。 |
| **permissions** | 当前后端用户必须具有的[权限](https://octobercms.com/docs/backend/users#users-and-permissions)才能使用该列。支持单个权限的字符串或仅需要一个权限即可授予访问权限的一组权限。 |
### [](https://octobercms.com/docs/backend/lists#displaying-list)显示清单
通常，列表显示在索引[视图](https://octobercms.com/docs/backend/controllers-ajax/#introduction)文件中。由于列表包括工具栏，因此视图文件将仅包含单个`listRender`方法调用。
~~~
<?= $this->listRender() ?>
~~~
### [](https://octobercms.com/docs/backend/lists#multiple-list-definitions)多个列表定义
列表行为可以使用命名定义在同一控制器中支持多个列表。该`$listConfig`属性可以定义为一个数组，其中键是定义名称，值是配置文件。
~~~
public $listConfig = [
'templates' => 'config_templates_list.yaml',
'layouts' => 'config_layouts_list.yaml'
];
~~~
然后，可以通过在调用`listRender`方法时将定义名称作为第一个参数传递来显示每个定义：
~~~
<?= $this->listRender('templates') ?>
~~~
- 基本说明
- 基本操作
- October cms 安装
- 后台控制器路径
- 图标
- 获取安装网上的插件/主题
- 插件构造器使用
- 定时任务
- October后台控制器
- vscode编辑器
- ajax操作
- 使用
- ajax更新组件
- ajax属性API
- JavaScript API
- ajax综合使用
- 主题
- 多语言主题
- 安装市场主题
- 主题程序处理
- 主题
- 页面
- 部件
- 布局
- 内容
- 组件
- 媒体
- 主题表单操作
- 表单使用
- 表单后端程序处理
- 插件
- 自定义插件
- 插件说明
- 插件导航条
- 插件数据库设置
- 插件的设置管理
- 插件的配置文件config
- 组件
- app服务
- app容器
- 扩展行为
- 缓存
- Collection类
- Lazy Collections
- Collection方法
- 助手函数
- 数组助手函数
- 路径助手函数
- 玄乐助手函数
- 其他助手函数
- 错误与记录
- 事件处理
- HTML页面
- 文件与目录操作
- 散列和加密
- 邮件
- 邮件内容
- 邮件发送
- 分页
- 模板解析器
- 动态解析器语法
- 队列消息
- 请求与输入
- 响应
- 视图
- 路由器
- 配置
- 验证操作
- 处理错误消息
- 错误消息与视图
- 可用的验证规则
- 有条件的验证规则
- 验证数组
- 错误消息
- 自定义验证规则
- 模型操作
- 定义模型与其属性
- 检索模型
- 插入与更新
- 删除模型
- 查询范围
- 事件操作
- 关联操作
- 定义关系
- 关系类型
- 多肽关系
- 关系查询
- 渴望加载
- 插入模型
- 数据库操作
- 基本用法
- 数据表结构
- 查询连贯操作
- 结果检索
- select子句
- 插入更新
- where子句
- 排序，分组，限制和偏移
- 文件附件
- Collection操作
- 属性操作
- 系列化json
- 数据库属性
- 数据库行为
- 控制器
- 后台控制器定义
- 后台页面
- 后台组件
- 后台表单
- 表单组件
- 表单视图
- 表单行为
- 后台列表
- 列表行为
- 列表过滤器
- 可用列类型
- 关系行为
- 关系行为类型
- 扩展关系行为
- 列表排序操作
- 导入导出操作
- 用于与权限
- corlate模板修改
- 修改顶部导航
- laravel问题
- 控制器不存在
- 控制器
- 路由组
- laravel笔记
- laravel 安装
- 伪静态配置
- 依赖注入 & 控制器
- 中间件
- 路由文件
- 视图