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 が公開されているか確認してください。公開されていない場合は、GitHub リポジトリを指す ルートの composer.json に repositories → vcs エントリーを追加し、composer require vendor/package:dev-main（またはタグ）を実行してください。パッケージが登録またはエイリアスされるまでは、通常の composer require webconsulting/records-list-types は失敗します。

TYPO3 API を優先： カスタム実装を作成する前に、必ず TYPO3 の組み込み API、コア機能、確立された規約を使用してください。TYPO3 がすでに提供している機能を再実装しないでください。使用する API やメソッドが TYPO3 v14 に存在し、非推奨になっていないことを、必ず TYPO3 の公式ドキュメントで確認してください。

1. 概要

TYPO3 バックエンドの レコードモジュールに、複数の表示モードを追加します。

表示形式	説明	適した用途
リスト	標準の TYPO3 テーブル（変更なし）	データ量の多いテーブル、システムレコード
グリッド	サムネイルとドラッグ＆ドロップに対応したカードレイアウト	ニュース、製品、チームメンバー、メディア
コンパクト	固定列を備えた、密度の高い1行形式	アドレス帳、ログ、設定、一括データ
ティーザー	タイトル、日付、抜粋を表示するシンプルなカード	ブログ記事、イベント、プレスリリース
カスタム	TSconfig と Fluid を使った独自の表示形式	タイムライン、カンバン、カタログ、ギャラリー

すべての表示形式に、ページネーション、並べ替え、検索、レコードアクション、ワークスペースのインジケーター、ダークモード、WCAG 2.1 アクセシビリティが含まれます。

機能

• グリッド表示 -- サムネイル、ドラッグ＆ドロップによる並べ替え、フィールド表示に対応したカード形式のレイアウト
• コンパクト表示 -- 固定列と横スクロールを備えた、密度の高い1行形式
• ティーザー表示 -- タイトル、日付、説明文の抜粋を表示するニュース形式のカード
• カスタム表示 -- PSR-14 イベントまたは TSconfig を使って、独自の表示タイプを登録
• ドラッグ＆ドロップ -- WCAG 2.1 に完全準拠した、マウスとキーボードによる並べ替え
• 言語フラグ -- グリッドカード内の各レコードに言語フラグアイコンを表示
• ワークスペース対応 -- 新規、変更、移動、削除されたレコードを色分けして表示
• ダークモード -- TYPO3 のダークモード（ライト／ダークテーマ）に完全対応
• テーブルごとの設定 -- TSconfig を使ってタイトル、説明、画像、表示フィールドを設定
• ユーザー設定 -- 表示モードは AJAX 経由でバックエンドユーザーごとに保存
• 並べ替えコントロール -- ドラッグによる手動並べ替えと、方向切り替えに対応したフィールドベースの並べ替え
• ページネーション -- TYPO3 コアに準拠：複数テーブルモードではレコードを制限して表示し、「テーブルを展開」ボタンを表示。単一テーブルモードでは完全なページネーション（レコード範囲、ページ入力、最初／前／次／最後）を表示
• 画像プレビューのヒント -- 特定のレコードタイプでは画像がフロントエンドに表示されない場合があることを、編集者に知らせる控えめな通知をサムネイルの下に表示
• 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 画像フィールドから自動的に解決されます（テーブルごとに設定可能）
• フィールド表示：型に応じた書式設定 -- ブール値はバッジ、日付は等幅フォント、リレーションは件数インジケーター、リンクはクリック可能、テキストは省略記号付きで切り詰められます
• 2 列のフィールドレイアウト：小さなフィールドは横並びで表示され、テキスト／リッチテキストフィールドは全幅を使用します
• ドラッグ＆ドロップ：マウスとキーボードの両方に対応（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 に対応するテーブルでは、2 つのモードを使用できます。

• 手動：ドラッグ＆ドロップで並べ替え（デフォルト）
• フィールド：昇順／降順の切り替えで列を基準に並べ替え

セグメント切り替えでモードを切り替えます。ドラッグ＆ドロップはマウスとキーボードの両方に対応します（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);
}

完全なドキュメント：テンプレート変数、実際の使用例、アセットの読み込み、PSR-14 による登録、ページスコープの表示を含む完全なリファレンスは、SKILL-CUSTOM-VIEWS.md を参照してください。

組み込みテンプレートを再利用する

新しいテンプレートは不要です -- カスタム列を使って既存のテンプレートを再利用できます。

# 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. カラム表示

表示するフィールドは、次の 2 つのモードで制御します。

モード	設定	動作
エディター制御	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	文字列	必須	表示名（LLL: に対応）
icon	文字列	必須	TYPO3 アイコン識別子
description	文字列		ツールチップ
template	文字列	<Id>View	Fluid テンプレート名
partial	文字列	Card	デフォルトのパーシャル
templateRootPath	文字列		カスタムテンプレートのパス
partialRootPath	文字列		カスタムパーシャルのパス
layoutRootPath	文字列		カスタムレイアウトのパス
css	文字列		CSS ファイル（EXT: 構文）
js	文字列		JS モジュール（@vendor/module.js）
columnsFromTCA	bool	1	エディターのカラム選択を使用します
displayColumns	文字列		カンマ区切りのフィールドリスト
itemsPerPage	int	100	1 ページあたりのレコード数（0 = ページネーションなし）

11. ワークスペースのサポート

ワークスペース内のレコードは、色分けされたインジケーターとともに表示されます。

状態	色	表示
新規	青	青いヘッダー＋左ボーダー
変更済み	紫	紫のヘッダー＋左ボーダー
移動済み	シアン	シアンのヘッダー＋左ボーダー
削除済み	赤	赤いヘッダー＋取り消し線付きタイトル

ワークスペースのオーバーレイは BackendUtility::workspaceOL() を介して適用されます。

Note: ワークスペースのサポートは実験的です。視覚的なインジケーターは機能しますが、ワークスペース内でのドラッグ＆ドロップのテストは限定的です。

詳細リファレンス

詳細な例、長いテンプレート、トラブルシューティングの表、付録、または上記に含まれていないセクションが必要な場合は、完全ガイドをお読みください。対象を絞った作業では、このファイルを読み込まずにおき、スキルが段階的に情報を開示するようにしてください。