安企CMS以其强大的内容模型和灵活的自定义字段功能，为网站运营者提供了极大的便利。这些自定义字段是网站内容个性化和数据结构化的关键。那么，如何准确地查询到一个特定模型（比如文章模型）所包含的所有自定义字段信息呢？这在进行二次开发、数据对接或者仅是为了了解系统结构时都非常有用。

在安企CMS中，要查询一个模型所包含的所有自定义字段信息，最直接有效的方式就是通过 获取模型详情接口（/api/module/detail） 来查询。

通过获取模型详情接口了解自定义字段

当你需要了解特定模型（例如文章模型或产品模型）的自定义字段定义时，可以使用这个接口。你只需提供模型的ID或其别名（filename），就能获取到该模型的所有详细信息，其中就包括了我们关心的自定义字段。

这个接口的调用方法是 GET，需要传入以下参数之一：

  • id：模型的唯一标识符，一个整数值。
  • filename：模型的URL别名，一个字符串。

例如，如果你知道文章模型的ID是1，你可以这样构建请求：{域名地址}/api/module/detail?id=1。

接口返回的数据结构中，在data对象下会有一个fields数组。这个fields数组就是该模型下所有自定义字段的完整定义。每个数组项都代表一个自定义字段，并包含以下关键信息：

  • name（字段中文名称）：这是你在安企CMS后台设置时看到的直观名称，方便内容编辑人员理解。
  • field_name（字段名称）：这是程序中调用的唯一标识符，通常用于模板标签、前端渲染或通过API进行数据交互时指定字段。
  • type（字段类型）：它指明了该字段的数据类型，例如text（文本）、number（数字）、textarea（多行文本）、radio（单选）、checkbox（多选）、select（下拉选择）等。了解字段类型有助于你正确处理和展示数据。
  • required（是否必填）：这是一个布尔值（true或false），指示该字段在发布内容时是否必须填写。
  • is_system（是否系统内置字段）：同样是布尔值，true表示这是系统自带的核心字段，false则表示是用户自定义添加的字段。
  • is_filter（是否筛选参数）：这个属性非常实用，如果为true，说明这个字段在前端内容列表中可以作为筛选条件，用户可以通过该字段的值来过滤内容。
  • follow_level（是否跟随文档阅读等级）：如果为true，意味着该自定义字段的可见性会受到文档阅读等级的限制。
  • content（默认值）：如果该字段在模型设置时配置了默认值，那么这个属性会显示相应的默认内容。对于下拉选择、单选、多选等类型，这里可能会包含选项列表。

通过解析这个fields数组，你就能够清楚地掌握某个模型下所有自定义字段的名称、类型、是否必填以及其他重要属性。

查询所有模型及其自定义字段

如果你想一次性了解所有模型及其自定义字段概况，或者不确定某个模型的具体ID或别名， 获取模型列表接口（/api/module/list） 会是你的好帮手。

这个接口的调用方法是 GET，并且无需任何参数，就能返回系统内所有内容模型的详细列表。在返回的data数组中，每个元素都是一个模型对象，其中同样包含了fields数组，其结构与获取模型详情接口返回的字段定义一致。这使得你可以遍历所有模型，并逐一查看它们各自的自定义字段定义。

理解文档中的自定义字段值

了解了自定义字段的定义后，接下来我们可能会想，如何查看一篇具体文章或产品中这些自定义字段实际填写了哪些内容呢？这可以通过 获取文档详情接口（/api/archive/detail） 或 获取文档列表接口（/api/archive/list） 来实现。

在这两个接口的返回数据中，你会看到一个名为extra的对象。extra对象里以field_name => item的形式展示了所有自定义字段的实际值。item对象通常包含：

  • name：自定义字段的中文名称。
  • value：该文档针对这个自定义字段实际填写的内容。
  • default：该字段的默认值（如果存在）。

通过结合使用上述几种API接口，无论是获取模型的字段定义，还是查询具体内容的字段值，安企CMS都提供了清晰便捷的途径，让你能够灵活地管理和利用网站的结构化内容。

常见问题 (FAQ)

  1. Q: is_filter字段有什么实际用途？ A: is_filter字段标记了某个自定义字段是否可以在网站前端作为筛选条件使用。例如，如果你的文章模型有一个名为“城市”的自定义字段，并且其is_filter为true，那么在文章列表页，你就可以基于“城市”字段的值来筛选文章，方便用户快速找到特定城市相关的文章。
  2. Q: 为什么我在获取文档详情接口的extra对象里，看不到某个自定义字段？ A: extra对象只包含那些已经填写了内容或者有默认值的自定义字段。如果某个自定义字段在后台模型中已经定义，但在具体的文档中没有填写任何内容，也没有设置默认值，那么它就不会出现在该文档的extra对象中。
  3. Q: field_name和name有什么区别？在开发中应该使用哪个？ A: name是自定义字段的中文显示名称，主要用于后台管理界面和提供给内容编辑人员直观识别。而field_name是字段的唯一标识符，它在程序内部、API请求参数以及模板标签中被使用。在开发中，尤其是在通过API进行数据交互时，你应该始终使用field_name来准确引用和操作自定义字段。