typo3-records-list-types

TYPO3 记录列表类型

来源：https://github.com/dirnbauer/webconsulting-skills

兼容性： TYPO3 v14.0+ / PHP 8.3+ 扩展键：records_list_types / Composer 包名：webconsulting/records-list-types GitHub：https://github.com/dirnbauer/typo3-records-list-types

扩展版本： 请以 webconsulting/records-list-types 的 GitHub 仓库 / composer.json 为准——此技能 YAML 中的 version 仅用于技能文档。

Composer / Packagist： 请在 Packagist 上确认是否已发布 webconsulting/records-list-types。如果尚未发布，请在根目录的 composer.json 中添加指向 GitHub 仓库的 repositories → vcs 条目，然后运行 composer require vendor/package:dev-main（或指定标签）。在该包注册或设置别名之前，直接运行 composer require webconsulting/records-list-types 会失败。

优先使用 TYPO3 API： 创建自定义实现之前，务必先使用 TYPO3 内置 API、核心功能和成熟约定。不要重复实现 TYPO3 已提供的功能。务必查阅 TYPO3 官方文档，确认所用 API 和方法存在且在 TYPO3 v14 中未弃用。

1. 概述

通过多种视图模式转换 TYPO3 后端的 记录 模块：

视图	描述	适用场景
列表	标准 TYPO3 表格（保持不变）	数据密集型表格、系统记录
网格	带缩略图的卡片布局，支持拖放	新闻、产品、团队成员、媒体
紧凑	密集的单行记录，固定列	地址簿、日志、设置、批量数据
摘要	带标题、日期、摘要的简洁卡片	博客文章、活动、新闻稿
自定义	通过 TSconfig + Fluid 创建自己的视图	时间线、看板、目录、图库

所有视图均包含：分页、排序、搜索、记录操作、工作区指示器、深色模式、符合 WCAG 2.1 的无障碍支持。

功能

• 网格视图 -- 基于卡片的布局，支持缩略图、拖放排序和字段显示
• 紧凑视图 -- 密集的单行记录，包含固定列并支持水平滚动
• 摘要视图 -- 新闻风格的卡片，包含标题、日期和描述摘要
• 自定义视图 -- 通过 PSR-14 事件或 TSconfig 注册自己的视图类型
• 拖放 -- 支持鼠标和键盘排序，并完全符合 WCAG 2.1 无障碍标准
• 语言标志 -- 在网格卡片中按记录显示语言标志图标
• 工作区支持 -- 以颜色区分新建、已修改、已移动和已删除的记录
• 深色模式 -- 完全兼容 TYPO3 深色模式（浅色/深色主题）
• 按表配置 -- 通过 TSconfig 配置标题、描述、图像和显示字段
• 用户偏好 -- 通过 AJAX 按后端用户保存视图模式
• 排序控件 -- 手动拖动排序，并可按字段排序及切换排序方向
• 分页 -- 与 TYPO3 Core 一致：多表模式显示有限数量的记录，并提供“展开表格”按钮；单表模式显示完整分页（记录范围、页码输入框、首页/上一页/下一页/末页）
• 图像预览提示 -- 在缩略图下方显示细微提示，提醒编辑者某些记录类型的图像可能不会显示在前端
• 零 PHP 可扩展性 -- 仅需 TSconfig + Fluid 模板 + CSS 即可添加新的视图类型，无需 PHP 类
• 搜索 -- 在所有视图模式中进行客户端搜索筛选
• 无障碍支持 -- 符合 WCAG 2.1 的键盘导航、ARIA 标签和屏幕阅读器支持

2. 安装

composer require webconsulting/records-list-types
./vendor/bin/typo3 extension:setup -e records_list_types

激活后，记录模块标题栏中会显示视图模式切换按钮。

3. 视图模式配置

设置默认视图和允许的视图

mod.web_list.viewMode {
    default = grid                          # Default for new users
    allowed = list,grid,compact,teaser      # Available in toggle
}

网格列数

mod.web_list.gridView.cols = 4    # 2-6 columns (default: 4)

视图模式解析顺序

1. URL 参数（?displayMode=grid）——优先级最高
2. 用户偏好（通过 AJAX 存储，按会话持久化）
3. TSconfig 默认值（mod.web_list.viewMode.default）
4. 回退：list

4. 按表配置字段

配置每个表的卡片上显示哪些字段：

mod.web_list.gridView.table.<tableName> {
    titleField = title              # Card title (default: TCA ctrl.label)
    descriptionField = teaser       # Card body text
    imageField = fal_media          # FAL field for thumbnail
    preview = 1                     # Enable thumbnails (1/0)
}

常用表

# News
mod.web_list.gridView.table.tx_news_domain_model_news {
    titleField = title
    descriptionField = teaser
    imageField = fal_media
    preview = 1
}

# Pages
mod.web_list.gridView.table.pages {
    titleField = title
    descriptionField = abstract
    imageField = media
    preview = 1
}

# Content Elements
mod.web_list.gridView.table.tt_content {
    titleField = header
    descriptionField = bodytext
    imageField = image
    preview = 1
}

# Frontend Users
mod.web_list.gridView.table.fe_users {
    titleField = name
    descriptionField = email
    imageField = image
    preview = 1
}

5. 视图模式详情

网格视图

• 卡片结构：标题栏（图标、标题、拖动手柄、操作）、可选缩略图（16:9）、字段值主体、页脚（UID、PID、语言标志）
• 缩略图：自动从 FAL 图像字段解析（可按表配置）
• 字段显示：根据类型格式化——布尔值显示为徽标，日期使用等宽字体，关联项显示计数指示器，链接可点击，文本过长时以省略号截断
• 双列字段布局：小字段并排显示；文本/富文本字段占满整行
• 拖放：支持鼠标和键盘（按 Space 抓取，按方向键移动，按 Space 放下，按 Escape 取消）
• 记录操作：可直接切换可见性、编辑、删除，还可通过下拉菜单查看信息、历史记录、复制和剪切
• 状态指示器：隐藏记录使用琥珀色标题栏；工作区记录使用蓝色/紫色/青色/红色标题栏
• 语言标志：每张卡片的右下角都会显示记录的语言标志图标
• 响应式网格：从最小宽度为 320px 的列开始自动填充，屏幕较窄时显示 1 列，宽屏时显示多列

紧凑视图

• 固定列：图标、UID 和标题固定在左侧；状态切换、编辑和删除固定在右侧
• 可滚动中间区域：其他字段可在固定列之间水平滚动
• 滚动阴影：当内容超出可视区域时显示视觉指示
• 可排序表头：点击列标题，通过 TYPO3 原生下拉菜单 API 按升序/降序排序
• 斑马纹：交替使用不同行颜色，提高可读性
• 隐藏记录样式：隐藏记录使用柔和的背景色，标题颜色变暗

摘要视图

• 简洁设计：标题、带日历图标的日期、描述摘要（限制为 2 行）
• 状态徽标：UID 标记和隐藏/可见指示器
• 精简操作：可见性切换、编辑和删除按钮
• 隐藏状态：隐藏记录带有强调色条
• CSS light-dark()：支持原生主题切换

6. 分页

与 TYPO3 Core List View 行为一致：

• 多表模式：限制每个表显示的记录数，并提供“展开表格”按钮
• 单表模式：完整分页（记录范围、页码输入框、首页/上一页/下一页/末页）

# Global default items per page
mod.web_list.viewMode.itemsPerPage = 100

# Per-type override
mod.web_list.viewMode.types.grid.itemsPerPage = 100
mod.web_list.viewMode.types.compact.itemsPerPage = 300
mod.web_list.viewMode.types.teaser.itemsPerPage = 100

# Disable pagination
mod.web_list.viewMode.types.grid.itemsPerPage = 0

7. 排序

支持 TCA sortby 的表有两种模式：

• 手动：拖放重新排序（默认）
• 字段：按列排序，并可切换升序/降序

通过分段切换控件在两种模式之间切换。拖放支持鼠标和键盘（按 Space 抓取，按方向键移动，按 Space 放下，按 Escape 取消）。

8. 自定义视图类型（快速入门）

只需 3 步即可添加视图——无需 PHP。

步骤 1：通过 TSconfig 注册

mod.web_list.viewMode {
    allowed = list,grid,compact,teaser,timeline

    types.timeline {
        label = Timeline
        icon = actions-calendar
        template = TimelineView
        templateRootPath = EXT:my_sitepackage/Resources/Private/Backend/Templates/
        css = EXT:my_sitepackage/Resources/Public/Css/timeline.css
        displayColumns = label,datetime,teaser
        columnsFromTCA = 0
    }
}

步骤 2：创建 Fluid 模板

将扩展中的 GenericView.html 复制为起点。关键变量：tableData、tableData.records、record.title、record.displayValues。

步骤 3：添加 CSS（可选）

使用 TYPO3 CSS 变量以自动支持深色模式：

.timeline-item {
    /* TYPO3 Core fallbacks; `--gv-*` tokens are defined by this extension, not by TYPO3 Core */
    background: var(--typo3-component-bg, #fff);
    border: 1px solid var(--typo3-component-border-color, #d4d4d8);
}

完整文档：请参阅 SKILL-CUSTOM-VIEWS.md，了解完整参考，包括模板变量、实际示例、资源加载、PSR-14 注册和页面作用域视图。

复用内置模板

无需新建模板——使用自定义列复用现有模板：

# Address book using CompactView with fixed columns
mod.web_list.viewMode.types.addressbook {
    label = Address Book
    icon = actions-user
    template = CompactView
    displayColumns = name,email,phone,company,city
    columnsFromTCA = 0
    itemsPerPage = 500
}

页面作用域视图

将视图限制为特定页面：

[traverse(page, "uid") == 42]
    mod.web_list.viewMode {
        allowed = list,timeline
        default = timeline
    }
[END]

9. 列显示

两种模式控制显示哪些字段：

模式	设置	行为
编辑器控制	columnsFromTCA = 1	遵循编辑器的“显示列”选择
固定布局	columnsFromTCA = 0	严格使用 displayColumns 列表

columnsFromTCA = 1 解析顺序

1. 编辑器的“显示列”选择（按用户和数据表分别存储）
2. 此扩展自身的 TSconfig / 模板解析——不是 Core mod.web_list.table.<table>.showFields（该路径并非有文档说明的 Core 列选择器）。请参阅扩展文档以及对应版本的 GridConfigurationService 行为。
3. TCA ctrl.label 和合理的文本/日期回退项（见下文“特殊列名称”）——TYPO3 v14 移除了 ctrl.searchFields；现在后端搜索会自动包含合适的字段，并可通过每列的 searchable 进行调整，该设置与此列表显示无关。
4. 仅显示标签字段（最终回退项）

特殊列名称

名称	解析为
label	TCA ctrl.label 字段（记录标题）
datetime	第一个日期字段（datetime、date、starttime、crdate）
teaser	第一个描述字段（teaser、abstract、description、bodytext、short）

10. TSconfig 参考

视图类型选项

选项	类型	默认值	描述
label	string	必填	显示名称（支持 LLL:）
icon	string	必填	TYPO3 图标标识符
description	string		工具提示
template	string	<Id>View	Fluid 模板名称
partial	string	Card	默认局部模板
templateRootPath	string		自定义模板路径
partialRootPath	string		自定义局部模板路径
layoutRootPath	string		自定义布局路径
css	string		CSS 文件（EXT: 语法）
js	string		JS 模块（@vendor/module.js）
columnsFromTCA	bool	1	使用编辑器的列选择
displayColumns	string		逗号分隔的字段列表
itemsPerPage	int	100	每页记录数（0 = 不分页）

11. 工作区支持

工作区中的记录会显示彩色指示标记：

状态	颜色	外观
新建	蓝色	蓝色标题栏 + 左侧边框
已修改	紫色	紫色标题栏 + 左侧边框
已移动	青色	青色标题栏 + 左侧边框
已删除	红色	红色标题栏 + 删除线标题

通过 BackendUtility::workspaceOL() 应用工作区覆盖。

**注意：**工作区支持尚处于实验阶段。视觉指示标记可正常使用，但工作区内的拖放功能测试有限。

详细参考

如果任务需要详细示例、长模板、故障排查矩阵、附录或上文未包含的章节，请阅读完整指南。对于范围较窄的任务，请勿加载此文件，以便技能遵循渐进式披露。