在安企CMS中，文档的自定义字段是其强大灵活性的一个体现，它们允许我们为内容添加各种独特属性，从而更精细地管理和展示信息。但对于许多开发者和运营人员来说，如何通过API准确地获取这些自定义字段的值，常常是一个需要明确的问题。别担心，安企CMS在API设计上提供了清晰的路径，通过 extra 字段，您便能轻松驾驭这些额外数据。

理解 extra 字段：自定义数据的宝库

当您通过安企CMS的API请求单个文档详情或文档列表时，返回的数据中通常会包含一个名为 extra 的字段。这个 extra 字段，顾名思义，是“额外”信息的集合，专门用于存放您在后台为文档模型配置的所有自定义字段及其对应的值。它是一个对象类型，其内部结构设计得非常直观，方便您进行编程访问。

具体来说，extra 对象内部的每一个键（key）都对应着您在安企CMS后台创建自定义字段时所设定的“表单字段调用名”（field_name）。而这个键所对应的值，又是一个包含三个属性的小对象：

  • name：这是自定义字段的中文名称，方便理解。
  • value：这是该自定义字段实际填写的内容，也就是您最希望获取的数据。
  • default：如果用户没有填写该字段，它会显示您在后台设置的默认值。

如何获取特定自定义字段的值？以“作者”为例

假设我们现在要获取一篇文档的“作者”信息。在安企CMS的后台，您可能已经为文章模型添加了一个名为“作者”，其“表单字段调用名”为 author 的自定义字段。

要获取这篇文档的详细信息，我们通常会使用 archive/detail 接口。您可以通过文档的 ID 或其 URL 别名（filename） 来请求这个接口。例如，请求某个 ID 为 1 的文档：

GET {域名地址}/api/archive/detail?id=1

接口返回的数据会是一个 JSON 结构，其中 data 对象包含了文档的所有详细属性。在 data 内部，您会找到 extra 字段，它可能看起来像这样：

{
  "code": 0,
  "data": {
    "id": 1,
    "title": "欢迎使用AnqiCMS",
    // ... 其他常规字段 ...
    "extra": {
      "author": {
        "name": "作者",
        "value": "AnqiCMS",
        "default": ""
      },
      "certificate": {
        "name": "学历",
        "value": null,
        "default": null
      },
      "city": {
        "name": "城市",
        "value": "北京\n上海\n重庆\n广州\n天津",
        "default": "北京\n上海\n重庆\n广州\n天津"
      }
    },
    // ... 其他字段 ...
    "link": ""
  },
  "msg": ""
}

从上面的示例中，我们可以清晰地看到 extra 对象内有一个 author 键。要获取作者的实际名称，您只需沿着数据路径 data.extra.author.value 即可。在您的编程语言中，这通常表现为 response.data.extra.author.value。例如，如果 response 是解析后的 JSON 对象，那么 response.data.extra.author.value 就会返回 "AnqiCMS"。

适用于文档列表的自定义字段获取

不仅是单个文档详情，当您通过 archive/list 接口获取一系列文档列表时，每个文档项的 extra 字段同样会包含其自定义字段信息。这意味着您可以轻松地在文章列表、产品展示页等地方，直接展示作者、来源、特定属性等自定义信息，而无需为每个列表项单独请求详情。

获取方式与 archive/detail 接口完全相同。在遍历文档列表时，对于每个文档对象，您仍然是根据自定义字段的“表单字段调用名”来访问其 extra 对象中的对应 value。

实用提示与注意事项

  1. 字段调用名是关键：务必记住您在后台自定义字段设置中定义的“表单字段调用名”（field_name）。这是通过API编程获取其值的唯一标识。如果忘记，可以通过 api/module/detail 接口获取模型详情，其中会列出所有自定义字段的 field_name。
  2. 处理空值情况：并非所有文档都会填写所有自定义字段，或者某个字段可能在某些文档模型中根本不存在。在您的代码中，请务必对 extra 对象以及其内部的自定义字段进行空值判断，以避免程序运行时出现错误。例如，在尝试访问 data.extra.author.value 之前，先检查 data.extra 是否存在，以及 data.extra.author 是否存在。
  3. 区分 name 和 value：extra 字段下每个自定义字段对象都有 name 和 value 两个属性。name 是字段的显示名称（如“作者”），而 value 才是您真正需要的内容（如“AnqiCMS”）。

通过理解并善用 extra 字段，安企CMS为您提供了极其便捷的方式来管理和展示丰富多样的内容属性，让您的网站或应用内容更具深度和灵活性。

常见问题 (FAQ)

Q1: 如果我不知道自定义字段的“表单字段调用名”怎么办？ A1: 您可以通过两种方式确认：首先，登录安企CMS后台，进入“内容管理” -> “模型管理”，找到对应的文档模型并点击编辑，其中会列出该模型下所有自定义字段及其“表单字段调用名”。其次，您也可以调用 api/module/detail 接口，传入模型 ID，在返回的 data.fields 数组中查找您想要的自定义字段，其 field_name 属性就是对应的调用名。

Q2: 为什么我获取到的 extra 字段是空的或者不包含我想要的自定义字段？ A2: 这通常有几个原因：

1.  **文档未填写该字段**：如果该文档在编辑时，您在对应的自定义字段中留空了，那么 `extra` 中该字段的 `value` 就会是 `null`。
2.  **字段不属于该文档模型**：您可能试图获取的自定义字段并不属于当前文档所使用的模型。请检查后台模型配置。
3.  **接口类型**：只有 `archive/detail` 和 `archive/list` 这两个接口会在 `data` 中返回 `extra` 字段，其他接口如 `archive/prev` 或 `archive/next` 通常不包含此信息。

Q3: data.extra.your_field.name 和 data.extra.your_field.value 有什么区别？我应该用哪个？ A3: data.extra.your_field.name 返回的是您在后台为该自定义字段设置的显示名称（例如“作者”）。而 data.extra.your_field.value 返回的则是用户在编辑文档时为该字段实际填写的内容（例如“AnqiCMS”）。在大多数情况下，您会希望获取和展示的是用户填写的内容，因此应该使用 data.extra.your_field.value。