内容类型构建器（Content-type Builder）

页面摘要： 内容类型构建器是用于设计内容类型和组件的工具。本文档对内容类型构建器进行概述，并涵盖字段选项、关系、组件用法，以及分享数据建模技巧。

通过管理面板主导航可访问的 内容类型构建器（Content-type Builder），用户可以创建和编辑他们的内容类型。

• Role & permission：Roles > Plugins - Content Type Builder 中至少需具备“Read（读取）”权限。
• Environment：仅在开发环境中可用。

概述

内容类型构建器允许创建和管理内容类型，这些内容类型可以是：

• Collection types（集合类型）：可以管理多个条目的内容类型。
• Single types（单一类型）：只能管理一个条目的内容类型。
• Components（组件）：可用于多个集合类型和单一类型的内容结构。虽然从技术上讲它们不是真正的内容类型（因为它们无法独立存在），但组件也通过内容类型构建器创建和管理，方式与集合类型和单一类型相同。

这三类都会在 内容类型构建器的子导航中作为类别显示。每个类别中列出了所有已经创建的内容类型和组件。

集合类型和单一类型也可以归类到文件夹中，以随着项目增长保持子导航的井然有序。

在内容类型构建器的子导航中还显示一个集中的 Save（保存） 按钮，它适用于所有内容类型和组件。连同内容类型/组件和字段状态的显示，这让你能够同时处理多个内容类型和组件。可能显示以下状态：

• New 或 N 表示某个内容类型/组件或字段是新的，尚未保存，
• Modified 或 M 表示某个内容类型/组件或字段自上次保存后被修改过，
• Deleted 或 D 表示某个内容类型/组件或字段已被删除，但只有在保存后才会最终确认。

配置

内容类型构建器无需配置即可使用。不过，用于组织内容类型的文件夹存储在一个专用文件中，可以直接编辑。

基于代码的配置

内容类型构建器子导航中显示的文件夹存储在 src/content-structure/groups.json 文件中。

该文件与项目的其余部分一起进行版本控制，因此本地定义的组织在部署时会与你的团队共享并随应用程序一起部署。

文件夹组织因此随你的项目代码一起移动：部署该文件即可将其从一个环境移动到另一个环境。 :::caution 数据传输 在导出、导入或传输中不包含内容结构文件。 ::: 在文件中，文件夹被称为 groups，并按 collectionTypes 和 singleTypes 两个分区分组列出。每个组都有一个标识符、名称、父级和子项列表：

{
  "version": 1,
  "sections": {
    "collectionTypes": {
      "groups": [
        {
          "id": "grp_x8k2m4p7q1",
          "name": "Restaurants",
          "parent": null,
          "children": [{ "type": "group", "id": "grp_c3v9n5t2w6" }]
        },
        {
          "id": "grp_c3v9n5t2w6",
          "name": "Menus",
          "parent": "grp_x8k2m4p7q1",
          "children": [{ "type": "contentType", "uid": "api::menu.menu" }]
        }
      ]
    },
    "singleTypes": {
      "groups": []
    }
  }
}

以下属性可用：

文件夹最多可以嵌套 3 层，一个内容类型只能属于一个文件夹。

手工编辑文件：Strapi 读取什么，以及对于无效文件会如何处理

在构建时，该文件会被编译为 dist/src/content-structure/groups.json，Strapi 在服务器启动时所读取的正是这个构建后的版本。

永远编辑源文件，不要编辑 dist 中的那个，后者会在下次构建时被替换。手工编辑的文件在应用程序被重新构建并重启后才会生效。

无法使用的条目会在启动时修复或忽略，并记录一条以 [content-structure] 为前缀的消息。例如：

• 对不再存在的内容类型的引用会从其所处文件夹中移除，
• 父级缺失的文件夹会被移回其分区的根部。

如果文件本身无法读取，服务器将在没有任何文件夹的情况下启动。

从内容类型构建器保存比在启动时读取文件更严格：违反上述任一规则的结构会被拒绝，而不是被修复。在构建和部署手工编写的文件之前，请确保它遵循这些规则。

使用

创建内容类型

内容类型构建器允许你创建新的内容类型：单一类型和集合类型，还有组件。

使用 Strapi AI 创建内容类型 （新增） {#strapi-ai}

（Growth 计划）

启用后，Strapi AI 会添加一个助手，帮助你用自然语言创建或编辑内容类型。

要将 Strapi AI 与内容类型构建器配合使用，请点击管理面板右下角的 按钮，并描述你的需求：

你还可以使用聊天窗口底部的 按钮，从现有的 Strapi 或前端应用程序导入代码、导入 Figma 项目，或附加一张图片以从设计中提取内容结构。

手动创建内容类型 {#new-content-type}

1. 选择你想创建的是集合类型还是单一类型。
2. 在 内容类型构建器中你想创建的内容类型的类别里，点击 Create new collection/single type（创建新的集合/单一类型）。
3. 在内容类型创建窗口中，在 Display name（显示名称） 文本框中填写新内容类型的名称。
4. 检查 API ID 以确保自动预填的值正确。集合类型名称在内容管理器中显示时确实会自动复数化。建议选择单数名称，但 API ID 字段允许你修正任何复数化错误。
5. （可选）在 Select a folder or enter a value to create a new one（选择文件夹或输入值以创建新文件夹） 字段中，选择内容类型应显示在哪个文件夹中，或键入一个名称以创建新文件夹（请参阅 使用文件夹组织内容类型）。
6. （可选）在 Advanced Settings（高级设置）标签页中，配置新内容类型的可用设置： | 设置名称 | 说明 | |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | Draft & publish（草稿与发布） | 勾选复选框以允许内容类型的条目在发布前作为草稿版本管理（请参阅 草稿与发布）。 | | Internationalization（国际化） | 勾选复选框以允许内容类型的条目被翻译为其他语言区域。 |
7. 点击 Continue（继续） 按钮。
8. 添加并配置为你的内容类型所选的字段（请参阅 为内容类型配置字段）。
9. 点击 Save（保存） 按钮。

:::caution 新内容类型只有在被保存后才会被视为已创建。只有在至少添加并正确配置了一个字段的情况下才能保存。如果未完成这些步骤，内容类型就无法被创建、无法在内容类型构建器中列于其类别下，也无法在 内容管理器 中使用。 :::

新建组件

1. 在 内容类型构建器子导航的 Components（组件）类别中，点击 Create new component（创建新组件）。
2. 在组件创建窗口中，配置新组件的基本设置：
   • 在 Display name（显示名称） 文本框中填写组件的名称。
   • 选择一个可用的类别，或在文本框中输入一个新的类别名称以创建一个。
   • （可选） 选择一个代表新组件的图标。你可以使用搜索 来查找图标，而不必滚动列表。
3. 点击 Continue（继续） 按钮。
4. 添加并配置为你的组件所选的字段（请参阅 为内容类型配置字段）。
5. 点击 Save（保存） 按钮。

编辑内容类型

内容类型构建器允许你管理所有现有的内容类型。对于要编辑的所选内容类型或组件，内容类型构建器界面的右侧会显示所有可用的编辑和管理选项。

设置

1. 点击你的内容类型的 Edit（编辑） 按钮以访问其设置。
2. 编辑你选择的可用设置：

基本设置（Basic settings）

• Display name（显示名称）：内容类型或组件在管理面板中显示的名称。
• API ID (singular)（API ID（单数））：内容类型或组件在 API 中使用的名称。它根据显示名称自动生成，但可编辑。
• API ID (plural)（API ID（复数））：内容类型或组件在 API 中使用的复数名称。它根据显示名称自动生成，但可编辑。
• Type（类型）：内容类型或组件的类型。可以是 Collection type（集合类型） 或 Single type（单一类型）。

高级设置（Advanced settings）

• Draft & Publish（草稿与发布）：为内容类型或组件启用 草稿与发布 功能。默认禁用。
• Internationalization（国际化）：为内容类型或组件启用 国际化 功能。默认禁用。

3. 在对话框中点击 Finish（完成） 按钮。
4. 在内容类型构建器导航中点击 Save（保存） 按钮。

字段

从列出你的内容类型字段的表格中，你可以：

• 点击 按钮，访问某个字段的基本和高级设置以进行编辑
• 点击 Add another field（添加另一个字段） 按钮，为所选内容类型创建一个新字段
• 点击 按钮并拖拽任意字段，以重排内容类型的字段
• 点击 按钮以删除一个字段

:::caution 编辑字段允许重命名它。但是请记住，就数据库而言，重命名字段意味着创建一个全新的字段并删除原来的字段。尽管不会从数据库中删除任何数据，但与原字段名相关联的数据将不再能从你的应用程序管理面板中访问。 :::

为内容类型配置字段 {#configuring-fields-content-type}

内容类型由一个或多个字段组成。每个字段旨在包含特定类型的数据，在内容管理器中填写（请参阅 创建与编写内容）。

在 内容类型构建器中，字段可以在创建新的内容类型或组件时添加，也可以在之后编辑或更新内容类型或组件时添加。

文本（Text） {#text}

文本（Text）字段显示一个可包含少量文本的文本框。此字段可用于标题、描述等。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

富文本（区块）（Rich Text (Blocks)） {#rich-text-blocks}

富文本（区块）字段显示一个具有实时渲染功能及各种选项来管理富文本的编辑器。此字段可用于较长的书面内容，甚至包括图片和代码。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

数字（Number） {#number}

数字（Number）字段显示用于任意类型数字的字段：整数、十进制和浮点数。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

日期（Date） {#date}

日期（Date）字段可以显示日期（年、月、日）、时间（时、分、秒）或日期时间（年、月、日、时、分、秒）选择器。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

密码（Password）

密码（Password）字段显示一个经过加密的密码字段。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

媒体（Media） {#media}

媒体（Media）字段允许你从应用程序媒体库中已上传的媒体文件（例如图片、视频）中选择一个或多个。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

关系（Relation） {#relation}

关系（Relation）字段允许你与另一个必须属于集合类型的内容类型建立关系。

共有 6 种不同类型的关系：

• 单向（One way）：内容类型 A 有一个（has one） 内容类型 B
• 一对一（One-to-one）：内容类型 A 拥有并属于一个（has and belong to one） 内容类型 B
• 一对多（One-to-many）：内容类型 A 属于多个（belongs to many） 内容类型 B
• 多对一（Many-to-one）：内容类型 B 拥有多个（has many） 内容类型 A
• 多对多（Many-to-many）：内容类型 A 拥有并属于多个（has and belongs to many） 内容类型 B
• 多向（Many way）：内容类型 A 拥有多个（has many） 内容类型 B

基本设置（Basic settings）

关系字段的基本设置包括选择应与哪个现有内容类型建立关系，以及关系的类型。关系字段的编辑窗口显示 2 个灰色框，每个代表关系中的一个内容类型。灰色框之间显示所有可能的关系类型。

1. 点击第 2 个灰色框以定义内容类型 B。它必须是一个已创建的集合类型。
2. 点击代表要在内容类型之间建立的关系的图标。
3. 选择内容类型 A 的 Field name（字段名称），即将在内容类型 A 中用于该字段的名称。
4. （如果关系类型未禁用则为可选）选择内容类型 B 的 Field name（字段名称）。

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

{
  populate: {
    children: {
      fields: ['title', 'slug'],
      populate: {
        children: {
          fields: ['title', 'slug'],
        },
      },
    },
  },
}

布尔值（Boolean） {#boolean}

布尔值（Boolean）字段显示一个开关按钮，用于管理布尔值（例如是或否、1 或 0、True 或 False）。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

JSON {#json}

JSON 字段允许你以 JSON 格式配置数据，以存储 JSON 对象或数组。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

邮箱（Email） {#email}

邮箱（Email）字段显示一个带格式验证的邮箱地址字段，以确保邮箱地址有效。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

密码（Password） {#password}

密码（Password）字段显示一个经过加密的密码字段。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

枚举（Enumeration） {#enum}

枚举（Enumeration）字段允许你配置一个显示在下拉列表中的值列表。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

:::caution 枚举值应始终在任意数字之前包含一个字母字符，否则在安装了 GraphQL 插件时，可能导致服务器在毫无提示的情况下崩溃。 :::

UID {#uid}

UID 字段显示一个设置唯一标识符的字段，可选择基于同一内容类型的某个现有其他字段。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

富文本（Markdown）（Rich Text (Markdown)） {#rich-text-markdown}

富文本（Markdown）字段显示一个带有基本格式选项的编辑器，用于管理以 Markdown 编写的富文本。此字段可用于较长的书面内容。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

组件（Components） {#components}

组件（Components）是若干字段的组合。组件允许你创建可复用的字段集，可以快速添加到内容类型、动态区域，也可以嵌套到其他组件中。

通过内容类型构建器配置组件时，你可以：

• 点击 Create a new component（创建新组件） 创建一个新组件（请参阅 新建组件），
• 或点击 Use an existing component（使用现有组件） 使用一个现有的组件。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

动态区域（Dynamic zones） {#dynamiczones}

动态区域（Dynamic zones）是组件的组合，可以添加到内容类型中。它们允许灵活的内容结构，因为在内容管理器中，管理员可以自由组合和重新排列动态区域的组件。

基本设置（Basic settings）

高级设置（Advanced settings）

条件（Condition）

1. 点击 应用条件 按钮。
2. 基于同一内容类型的布尔或枚举字段定义条件的 if 部分（例如如果 boolean_field 为 true）。
3. 通过选择隐藏还是显示你正在配置的字段来定义条件的 then 部分（例如 then show carousel_media）。

配置完动态区域的设置后，还必须配置其组件。可以选择现有组件或创建一个新组件。

:::caution 使用动态区域时，不同的组件不能拥有同名的字段但类型不同（或者对于枚举字段，值不同）。 :::

自定义字段（Custom fields）

自定义字段 是一种通过向内容类型或组件添加新的字段类型来扩展 Strapi 能力的方式。一旦安装（请参阅 应用市场 文档），自定义字段会在为内容类型选择字段时列于 Custom（自定义） 标签页中。

每种自定义字段类型都可以有基本和高级设置。Marketplace（应用市场） 列出了可用的自定义字段，并为每种自定义字段托管了专门的文档，包括特定的设置。

删除内容类型

内容类型和组件可以通过内容类型构建器删除。删除内容类型会自动删除内容管理器中基于该内容类型的所有条目。删除组件的情况也是如此，它会从中使用过它的每个内容类型或条目中自动删除。

1. 在 内容类型构建器子导航中，点击要删除的内容类型或组件的名称。
2. 在所选内容类型或组件的编辑界面中，点击内容类型或组件名称右侧的 Edit（编辑） 按钮。
3. 在编辑窗口中，点击 Delete（删除） 按钮。
4. 在确认窗口中，确认删除。
5. 在内容类型构建器子导航中点击 Save（保存） 按钮。

:::caution 删除内容类型只会删除在内容类型构建器中创建的内容，以及由此在 Strapi 应用程序管理面板中可用的内容。但是，基于该内容类型创建的所有数据都会保留在数据库中。更多信息，请参阅相关的 GitHub issue。 :::

使用文件夹组织内容类型 （新增） {#organizing-content-types-with-folders}

集合类型和单一类型可以归类到文件夹中，文件夹最多可以嵌套 3 层。文件夹显示在 内容类型构建器的子导航中。

它们也会显示在 内容管理器 中，帮助内容管理员更快地找到内容类型。

文件夹存储在项目的 内容结构文件 中。与在内容类型构建器中进行的任何其他更改一样，文件夹的更改只有在点击 Save（保存） 后才会应用。

创建文件夹

1. 在 内容类型构建器子导航中，打开 Collection types（集合类型） 或 Single types（单一类型） 类别的创建菜单，然后点击 New folder（新建文件夹）。
2. 填写文件夹的名称并按 Enter。
3. 点击 Save（保存） 按钮。

文件夹创建在其类别的根部，之后可以移动到另一个文件夹中。

移动内容类型和文件夹 {#moving-content-types-and-folders}

内容类型和文件夹通过在 内容类型构建器子导航中拖拽来移动。

将某项拖到文件夹上即可将其放入其中，将其拖出文件夹即可放回其类别根部，或上下拖拽以重排。

一个内容类型一次只能属于一个文件夹，且文件夹的嵌套限制为 3 层。

将内容类型和文件夹按你想要的方式组织好后，点击 Save（保存） 按钮。

重命名文件夹

1. 在 内容类型构建器子导航中，点击要重命名的文件夹的 按钮。
2. 点击 Rename（重命名）。
3. 填写文件夹的新名称并按 Enter。
4. 点击 Save（保存） 按钮。

删除文件夹

1. 在 内容类型构建器子导航中，点击要删除的文件夹的 按钮。
2. 点击以下选项之一：
   • Delete folder（删除文件夹），仅删除文件夹。它所包含的内容类型和文件夹会被移动到父文件夹，或者如果文件夹未嵌套则移动到类别根部。
   • Delete folder and contents（删除文件夹及其内容），删除文件夹及其所包含的内容类型和文件夹。此选项仅在文件夹非空时可用。
3. 在确认窗口（其中会标明有多少内容类型和文件夹受影响）中，点击 Yes, delete（是，删除）。
4. 点击 Save（保存） 按钮。

如果将子文件夹移出该文件夹会导致其目标位置出现两个同名的文件夹（不区分大小写），则 Delete folder（删除文件夹） 不可用。

确认窗口随后会列出冲突的名称，并且在其中一个文件夹被重命名之前，Yes, delete（是，删除） 会保持禁用。

:::caution Delete folder and contents（删除文件夹及其内容） 会删除文件夹、其子文件夹，以及为你的应用程序创建的内容类型，其后果与逐个删除这些内容类型相同（请参阅 删除内容类型）。

内容类型构建器不管理的内容类型（例如来自插件的内容类型）会被保留并移出文件夹，确认窗口会标明保留了多少个此类内容类型。

若要保留所有内容类型，请改用 Delete folder（删除文件夹）。 :::