后臺列表 · October Cms 筆記

# 后臺列表 ### 介紹 **列表行為**是控制器修改器，用于輕松地將記錄列表添加到頁面。該行為提供可排序和可搜索的列表，并在其記錄上帶有可選鏈接。該行為提供了控制器操作，`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') ?> ~~~