在使用安企CMS管理网站内容时，文档详情或文档列表接口（如 archiveDetail 和 archiveList）返回的数据中，经常会看到一个名为 extra 的字段。这个字段专门用于承载我们为文档模型设置的自定义信息。理解 extra 字段的结构以及它与后台自定义字段的对应关系，对于前端开发和内容管理都至关重要。

理解安企CMS的自定义字段机制

安企CMS提供了强大的自定义字段功能，允许用户根据不同类型的文档（例如文章、产品等）灵活地扩展其属性。在后台，当你进入“模型管理”并选择一个具体的文档模型（比如“文章模型”或“产品模型”）时，你可以为该模型添加或编辑自定义字段。

每个自定义字段在后台设置时，有几个核心属性需要关注：

  • 字段名称 (field_name)：这是字段在系统内部的唯一标识，也是我们通过API请求数据时，在 extra 字段中用作 key 的关键标识符。它通常是英文单词或拼音，例如“author”、“city”、“certificate”等。
  • 字段中文名称 (name)：这是在后台界面上显示给内容编辑人员看的友好名称，比如“作者”、“发布城市”、“学历”等。它帮助我们直观地理解字段的用途。
  • 字段类型 (type)：决定了该字段可以存储的数据类型，如文本（text）、数字（number）、单选（radio）、多选（checkbox）、图片（image）等。
  • 是否筛选 (is_filter)：标记该字段是否可以用于前端的筛选条件。
  • 默认值 (default/content)：为该字段设置的初始值。

正是通过这些后台的配置，extra 字段在API响应中得以动态呈现。

extra 字段的结构解析

当我们通过 archiveDetail 或 archiveList 接口获取文档数据时，如果文档所属的模型配置了自定义字段，这些字段的数据就会被打包到 data 对象下的 extra 字段中。

extra 字段的结构是 key => item 的形式：

  • key：这里的 key 直接对应了你在后台自定义字段设置中的“字段名称”（field_name）。这是前端开发者用来精确访问某个自定义字段值的唯一标识。比如，如果你在后台设置了一个 field_name 为 author 的自定义字段，那么在 extra 字段中，你就会看到一个名为 author 的键。
  • item：与 key 关联的 item 是一个对象，它包含了该自定义字段的详细信息和实际内容，通常包括以下属性：
    • name：这对应于你在后台为该字段设置的“字段中文名称”。例如，如果 key 是 author，那么 name 可能就是“作者”。它主要用于展示和理解。
    • value：这是当前文档在该自定义字段中实际填写或存储的内容。这是我们最常需要提取来显示的数据。
    • default：这个属性显示的是该自定义字段在后台设置的默认值。

让我们通过一个示例来具体说明：

"extra": {
  "author": {
    "name": "作者",
    "value": "AnqiCMS",
    "default": ""
  },
  "certificate": {
    "name": "学历",
    "value": null,
    "default": null
  },
  "city": {
    "name": "城市",
    "value": "北京\n上海\n重庆",
    "default": "北京\n上海\n重庆"
  }
}

从这个返回数据中，我们可以清晰地看到 author、certificate、city 这些 key，它们就是我们在后台为该模型定义的自定义字段的“字段名称”。每个 key 下的 item 对象又详细列出了该字段的“中文名称”（name）、“实际内容”（value）和“默认值”（default）。例如，要获取作者的名字，我们只需要访问 extra.author.value 即可。

实际应用场景

这种 extra 字段与自定义字段的对应机制，为网站的内容管理和前端展示带来了极大的灵活性：

  1. 动态内容展示：前端可以根据 extra 字段中的 key 动态地渲染页面内容，而无需修改后端代码或数据库结构。无论后台新增了多少自定义字段，前端都可以通过统一的 extra 结构来获取并展示。
  2. 筛选与搜索：如果自定义字段被标记为“可筛选”（is_filter=true），那么在 archiveFilters 接口中，你也会看到它的 field_name。这允许前端构建复杂的筛选器，让用户根据这些自定义字段的值来检索文档，从而提供更加精细化的内容导航体验。
  3. 数据导入与发布：在通过 archivePublish 或 importArchive 接口发布或导入文档时，自定义字段的数据也可以作为请求参数的一部分提交。此时，请求参数的键名同样要与后台定义的“字段名称”（field_name）保持一致。

通过这种设计，安企CMS将内容管理的灵活性与API数据传输的规范性完美结合，让网站运营者能够轻松扩展内容模型，同时也为开发者提供了清晰、可预测的数据结构。

常见问题解答 (FAQ)

1. 如果我在后台删除了一个自定义字段，API返回的 extra 字段中还会包含它吗？ 答：不会。extra 字段是动态生成的，它只会包含当前模型中实际存在的、并且在文档中填写了内容的自定义字段。一旦后台删除了某个自定义字段，或者文档在该字段中没有填写任何内容，该字段就不会在 extra 字段的返回数据中出现。

2. extra 字段中的 value 为 null 是什么意思？我应该如何处理？ 答：value 为 null 表示当前文档在后台的这个自定义字段中没有填写任何内容。如果后台为该字段设置了默认值，default 属性可能会显示默认值，但 value 仍会是 null，除非实际填写了内容。在前端处理时，应该检查 value 是否为 null，以便决定是显示默认值、显示空内容，还是进行其他逻辑处理。

**3. 我可以在 `