如何在文档列表中显示自定义的模型字段信息？

在安企CMS中，内容模型的灵活性是其突出优势之一。许多时候，我们不仅需要在文档详情页展示丰富的内容，还希望在文档列表页一眼就能看到关键的自定义信息，比如产品的型号、文章的作者、房产的价格、车辆的里程数等。这些信息往往是用户快速筛选和了解内容的重要依据。本文将详细讲解如何在安企CMS的文档列表中，巧妙地显示这些自定义的模型字段信息。

灵活定制：理解安企CMS的内容模型

安企CMS允许我们根据实际业务需求，创建各种各样的内容模型。例如，除了系统内置的文章和产品模型外，我们还可以创建像“新闻”、“案例”、“招聘”等模型。每个模型都可以拥有自己独特的一套字段，这些字段共同定义了该模型的结构和内容。

自定义字段是内容模型的灵魂。它们可以是简单的文本输入框，也可以是数字、多行文本、单选、多选甚至文件上传等多种类型。通过这些自定义字段，我们可以为内容添加更加具体和个性化的属性，从而更好地管理和展示我们的网站内容。

第一步：在后台定义自定义字段

要让自定义字段在文档列表中显示，首先我们需要确保这些字段已经在安企CMS后台的内容模型中被定义。

1. 进入内容模型管理：登录安企CMS后台，导航至“内容管理” -> “内容模型”。
2. 选择或创建模型：选择你想要添加自定义字段的模型（例如“文章模型”或“产品模型”），或者创建一个全新的内容模型。
3. 添加自定义字段：在模型编辑页面，找到“内容模型自定义字段”区域。点击“添加字段”，为你的模型添加所需的自定义信息。
   • 参数名：这是字段在后台管理界面显示的名称，通常是中文，易于理解（例如“产品型号”、“文章作者”）。
   • 调用字段：这是在模板中用于调用该字段的唯一标识，必须是英文字母。这是我们在前端模板中引用该字段的关键（例如“model_number”、“author_name”）。
   • 字段类型：根据你希望存储的数据类型选择，如“单行文本”、“数字”、“多行文本”等。
   • 是否必填：根据需求设置。
   • 默认值：可以预设一个值，用户在发布内容时如果没有填写，就会自动应用该默认值。
4. 保存模型：完成字段添加后，务必保存内容模型的更改。

完成这一步后，你在发布对应模型下的文档时，就会看到这些新增的自定义字段，并可以为它们填写内容。

第二步：修改模板，在列表页调用自定义字段

在安企CMS中，网站页面的呈现是由模板文件决定的。要在文档列表中显示自定义字段，我们需要修改对应列表页的模板文件。

安企CMS的模板遵循类似Django模板引擎的语法，变量使用双花括号 {{变量}}，逻辑控制使用 {% 标签 %}。模板文件通常存放在 /template 目录下，并按照一定的目录结构组织（例如 {模型table}/list.html 用于列表页）。

我们将主要使用 archiveList 标签来获取文档列表，并在循环中结合 archiveParams 标签来获取每个文档的自定义字段。

1. 定位列表页模板文件：

   • 假设你要在文章列表页显示自定义字段，你需要找到对应的文章列表模板，通常是 template/你的模板名称/article/list.html 或 template/你的模板名称/archive/list.html。
   • 如果你不确定具体是哪个文件，可以参考“模板制作的目录和模板”文档中关于“文档列表页”的命名约定。

2. 获取文档列表： 在列表模板中，通常会有一个 archiveList 标签来循环展示文档：

   
   {% archiveList archives with type="page" limit="10" %}
       {% for item in archives %}
           {# 这里是每个文档的显示区域 #}
           <a href="{{item.Link}}">
               <h5>{{item.Title}}</h5>
               <div>{{item.Description}}</div>
               {# ... 其他内置字段 ... #}
           </a>
       {% empty %}
           <p>目前没有文档。</p>
       {% endfor %}
   {% endarchiveList %}
   

   item 代表循环中的每一个文档对象，我们可以通过 item.Title、item.Link 等方式直接获取文档的内置字段。

3. 调用自定义模型字段： 自定义模型字段并不直接包含在 item 对象中。我们需要在 for 循环内部，针对每个文档，使用 archiveParams 标签来获取其自定义字段。archiveParams 标签需要传入当前文档的 ID 来获取对应的字段信息。

   {% archiveList archives with type="page" limit="10" %}
       {% for item in archives %}
           <div class="document-item">
               <a href="{{item.Link}}">
                   <h3>{{item.Title}}</h3>
                   <p>{{item.Description}}</p>
                   {# 显示自定义字段区域 #}
                   <div class="custom-fields">
                       {% archiveParams params with id=item.Id %}
                           {% for field in params %}
                               {# field.Name 是后台设置的“参数名”（中文） #}
                               {# field.Value 是该字段的具体内容 #}
                               <p><strong>{{field.Name}}:</strong> {{field.Value}}</p>
                           {% endfor %}
                       {% endarchiveParams %}
                   </div>
               </a>
           </div>
       {% empty %}
           <p>目前没有文档。</p>
       {% endfor %}
   {% endarchiveList %}
   

   在上面的代码中，我们通过 {% archiveParams params with id=item.Id %} 获取了当前 item（文档）的所有自定义字段，并将它们存储在 params 变量中。然后，我们再次使用 for 循环遍历 params 变量，就能显示每个自定义字段的名称和值了。

4. 按需显示特定自定义字段： 如果你只关心某个特定的自定义字段，并且知道它的“调用字段”名称（例如我们之前定义的 author_name），你也可以直接通过 archiveDetail 标签来获取：

   {% archiveList archives with type="page" limit="10" %}
       {% for item in archives %}
           <div class="document-item">
               <a href="{{item.Link}}">
                   <h3>{{item.Title}}</h3>
                   <p>{{item.Description}}</p>
                   {# 显示特定的自定义字段，例如“文章作者” #}
                   <p>
                       <strong>作者:</strong> {% archiveDetail with name="author_name" id=item.Id %}
                   </p>
               </a>
           </div>
       {% empty %}
           <p>目前没有文档。</p>
       {% endfor %}
   {% endarchiveList %}
   

   这种方式在只显示少量且固定的自定义字段时更为简洁。

注意事项

• 清除缓存：修改模板文件后，可能需要登录安企CMS后台，点击“更新缓存”按钮，才能让修改生效。
• 字段类型处理：
  • 多行文本（富文本）：如果自定义字段是多行文本或富文本编辑器类型，其内容可能包含HTML标签。在输出时，需要使用 |safe 过滤器来确保HTML被正确解析而不是作为纯文本显示，例如 {{field.Value|safe}}。
  • 图片类型：如果自定义字段是图片上传类型，其 field.Value 存储的是图片URL。在显示时，你需要将其包裹在 <img> 标签中：<img src="{{field.Value}}" alt="{{item.Title}}">。如果需要显示缩略图，可以使用 thumb 过滤器：<img src="{{field.Value|thumb}}" alt="{{item.Title}}">。
  • 多选/下拉选择：这些字段的值可能是一个数组或逗号分隔的字符串。根据实际存储格式，你可能需要进一步处理（例如使用 split 过滤器将字符串分割成数组，然后循环遍历显示）。
• 调用字段名准确性：务必使用在后台设置的“调用字段”名称（英文字母），而不是“参数名”（中文），并且注意大小写。

通过以上步骤和注意事项，你可以灵活地在安企CMS的文档列表中展示各种自定义的模型字段信息，从而大大提升网站内容的管理效率和用户体验。

常见问题 (FAQ)

1. 我在后台添加了自定义字段并修改了列表模板，但前端页面没有显示，是哪里出了问题？ 首先请确保你在后台修改内容模型后点击了“保存”，并且确认你在模板中使用了正确的“调用字段”名称（而非“参数名”）。同时，最重要的一个步骤是，登录安企CMS后台，点击左侧导航栏最下方的“更新缓存”按钮，清理系统缓存，这样模板修改才能及时生效。

2. 我的自定义字段是图片类型，为什么在列表页显示的是图片链接而不是图片本身？ 图片类型的自定义字段，其值通常是图片的URL地址。在模板中，你需要将这个URL放到 <img> 标签的 src 属性中才能显示图片。例如：<img src="{{field.Value}}" alt="{{item.Title}}">。如果你想显示缩略图，还可以使用 {{field.Value|thumb}} 过滤器。

3. 如果我的自定义字段是多选类型，在列表页如何显示多个被选中的值？ 多选字段的值通常会以逗号等分隔符存储在一个字符串中。你可以在模板中使用 split 过滤器将其分割成一个数组，然后通过 for 循环遍历显示每一个选项。例如：{% for option in field.Value|split:"," %} <span>{{option}}</span> {% endfor %}。具体的分隔符需要根据你后台设置的默认值格式来确定。