typo3-content-blocks

TYPO3 Content Blocks 开发

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

兼容性： 此技能面向 TYPO3 v14.3+ 和 Content Blocks 2.x。请务必使 Packagist friendsoftypo3/content-blocks 的约束与 Core 版本相匹配。 对于 TYPO3 v13 上的 Content Blocks 1.x，上游要求 TYPO3 ≥ 13.4（typo3/cms-core: ^13.4）——请在 Packagist 上确认。 示例使用 TYPO3 v14 API 和 CB 2.x；如果上游约束不同，请调整 composer.json。

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

迁移覆盖范围： Content Blocks 迁移和跨技能交接指南直接记录在此技能及其本地附加组件中。

1. 单一事实来源原则

Content Blocks 是在 TYPO3 中创建自定义内容类型的现代方式。它通过提供单一 YAML 配置来消除冗余，并生成：

• TCA（表配置数组）
• 数据库架构（SQL）
• TypoScript 渲染
• 后端表单和预览
• 标签和翻译

为什么选择 Content Blocks？

传统方式	Content Blocks 方式
多个 TCA 文件	一个 config.yaml
手动定义 SQL	自动生成架构
单独的 TypoScript	自动注册渲染
分散的翻译	单个 labels.xlf
复杂的设置	简单的文件夹结构

2. 安装

# Install via Composer (DDEV recommended)
ddev composer require friendsoftypo3/content-blocks

# After installation, clear caches
ddev typo3 cache:flush

版本约束： Content Blocks 1.x 要求 TYPO3 ≥ 13.4（软件包中的 typo3/cms-core: ^13.4）。TYPO3 13.1–13.3 不满足此 Composer 约束。

安全配置（经典模式）

对于非 Composer 安装，请禁止通过 Web 访问 ContentBlocks 文件夹：

# .htaccess addition
RewriteRule (?:typo3conf/ext|typo3/sysext|typo3/ext)/[^/]+/(?:Configuration|ContentBlocks|Resources/Private|Tests?|Documentation|docs?)/ - [F]

3. 内容类型概览

Content Blocks 支持四种内容类型：

类型	文件夹	表	用途
ContentElements	ContentBlocks/ContentElements/	tt_content	前端内容（主视觉、手风琴、CTA）
RecordTypes	ContentBlocks/RecordTypes/	自定义/现有	结构化记录（新闻、产品、团队）
PageTypes	ContentBlocks/PageTypes/	pages	自定义页面类型（博客、落地页）
FileTypes	ContentBlocks/FileTypes/	sys_file_reference	扩展文件引用（摄影师、版权）

4. 文件夹结构

EXT:my_sitepackage/
└── ContentBlocks/
    ├── ContentElements/
    │   └── my-hero/
    │       ├── assets/
    │       │   └── icon.svg
    │       ├── language/
    │       │   └── labels.xlf
    │       ├── templates/
    │       │   ├── backend-preview.fluid.html
    │       │   ├── frontend.fluid.html
    │       │   └── partials/
    │       └── config.yaml
    ├── RecordTypes/
    │   └── my-record/
    │       ├── assets/
    │       │   └── icon.svg
    │       ├── language/
    │       │   └── labels.xlf
    │       └── config.yaml
    ├── PageTypes/
    │   └── blog-article/
    │       ├── assets/
    │       │   ├── icon.svg
    │       │   ├── icon-hide-in-menu.svg
    │       │   └── icon-root.svg
    │       ├── language/
    │       │   └── labels.xlf
    │       ├── templates/
    │       │   └── backend-preview.fluid.html
    │       └── config.yaml
    └── FileTypes/
        └── image-extended/
            ├── language/
            │   └── labels.xlf
            └── config.yaml

5. 创建内容元素

Kickstart 命令（推荐）

# Interactive mode
ddev typo3 make:content-block

# One-liner
ddev typo3 make:content-block \
  --content-type="content-element" \
  --vendor="myvendor" \
  --name="hero-banner" \
  --title="Hero Banner" \
  --extension="my_sitepackage"

# After creation, update database
ddev typo3 cache:flush -g system
ddev typo3 extension:setup --extension=my_sitepackage

预定义基础项（内容元素）

在 basics: 下列出，以引入 Core 字段组：TYPO3/Header、TYPO3/Appearance、TYPO3/Links、TYPO3/Categories。请参阅 Content Blocks 基础项参考。

最小内容元素

# EXT:my_sitepackage/ContentBlocks/ContentElements/hero-banner/config.yaml
name: myvendor/hero-banner
fields:
  - identifier: header
    useExistingField: true
  - identifier: bodytext
    useExistingField: true

完整内容元素示例

# EXT:my_sitepackage/ContentBlocks/ContentElements/hero-banner/config.yaml
name: myvendor/hero-banner
group: default
description: "A full-width hero banner with image and CTA"
prefixFields: true
prefixType: full
basics:
  - TYPO3/Appearance
  - TYPO3/Links
fields:
  - identifier: header
    useExistingField: true
  - identifier: subheadline
    type: Text
    label: Subheadline
  - identifier: hero_image
    type: File
    minitems: 1
    maxitems: 1
    allowed: common-image-types
  - identifier: cta_link
    type: Link
    label: Call to Action Link
  - identifier: cta_text
    type: Text
    label: Button Text

前端模板

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:cb="http://typo3.org/ns/TYPO3/CMS/ContentBlocks/ViewHelpers"
      data-namespace-typo3-fluid="true">

<f:asset.css identifier="hero-banner-css" href="{cb:assetPath()}/frontend.css"/>

<section class="hero-banner">
    <f:if condition="{data.hero_image}">
        <f:for each="{data.hero_image}" as="image">
            <f:image image="{image}" alt="{data.header}" class="hero-image"/>
        </f:for>
    </f:if>
    
    <div class="hero-content">
        <h1>{data.header}</h1>
        <f:if condition="{data.subheadline}">
            <p class="subheadline">{data.subheadline}</p>
        </f:if>
        
        <f:if condition="{data.cta_link}">
            <f:link.typolink parameter="{data.cta_link}" class="btn btn-primary">
                {data.cta_text -> f:or(default: 'Learn more')}
            </f:link.typolink>
        </f:if>
    </div>
</section>
</html>

shadcn/ui 前端模板模式

当内容块需要遵循 shadcn/ui 样式时，应将内容块 YAML 保留为内容模型，并将重复的视觉结构移至共享 Fluid 组件中。frontend.fluid.html 入口应将 {data} 字段映射到带类型的原子组件，而不是在每个内容块中重复编写定制 CSS。

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:d="http://typo3.org/ns/Vendor/Sitepackage/Components/ComponentCollection"
      data-namespace-typo3-fluid="true">

<section class="py-12 md:py-16">
    <d:molecule.card class="mx-auto max-w-2xl">
        <d:molecule.cardHeader>
            <d:molecule.cardTitle>{data.header}</d:molecule.cardTitle>
            <f:if condition="{data.subheadline}">
                <d:molecule.cardDescription>{data.subheadline}</d:molecule.cardDescription>
            </f:if>
        </d:molecule.cardHeader>
        <d:molecule.cardContent>
            <f:format.html>{data.bodytext}</f:format.html>
        </d:molecule.cardContent>
    </d:molecule.card>
</section>
</html>

指南：

• 除非内容模型本身发生变化，否则请保留现有字段标识符、fixture.json、标签和编辑器工作流。
• 使用共享 Fluid 组件实现 Button、Badge、Card、Form 控件、Tabs、Accordion、Alert、Table 和 Sheet/Dialog 外壳等 shadcn 基础组件。
• 在可复用的 Fluid 组件和部分模板中声明 <f:argument> 类型契约。除非渲染上下文完全可控，否则不要在内容块入口模板中添加必填参数。
• 仅将 f:asset.css / f:asset.script 用于内容块专属资源。共享的 shadcn/Tailwind 设计令牌和实用工具类应放在站点 CSS 入口中。
• 对于交互式 shadcn 模式，应使用 Alpine 或简洁的原生 JavaScript 控制器，并配合 ARIA 和 data-state 属性，而非依赖 React/Radix 运行时。
• 创建或更新样式指南 fixture，确保每个内容块都能以真实内容在浅色和深色模式下渲染。

后端预览模板

<html xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
      xmlns:be="http://typo3.org/ns/TYPO3/CMS/Backend/ViewHelpers"
      data-namespace-typo3-fluid="true">

<div class="content-block-preview">
    <strong>{data.header}</strong>
    <f:if condition="{data.subheadline}">
        <br/><em>{data.subheadline}</em>
    </f:if>
    <f:if condition="{data.hero_image}">
        <f:for each="{data.hero_image}" as="image">
            <be:thumbnail image="{image}" width="100" height="100"/>
        </f:for>
    </f:if>
</div>
</html>

详细参考

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