安企CMS如何获取并显示文档的后台自定义参数字段？

安企CMS以其出色的灵活性和高度可定制性，深受内容运营者的喜爱。在日常网站管理中，我们经常会遇到需要为不同类型的内容（例如文章、产品、活动等）添加专属属性的场景。这时，安企CMS的文档自定义参数字段功能便能大显身手，它允许我们根据业务需求扩展内容的结构，从而实现更加个性化和丰富的展示效果。

本文将详细介绍如何在安企CMS后台创建这些自定义参数字段，以及如何在前端模板中准确获取并优雅地呈现它们，帮助你充分利用这一强大功能，让你的网站内容更具表现力。

什么是文档的自定义参数字段？

简单来说，自定义参数字段就是对安企CMS预设的内容结构进行扩展，为我们的文档添加额外的、独有的属性。例如，如果你的网站有“产品”模块，除了常规的产品名称、描述和图片外，你可能还需要记录产品的“价格”、“库存量”、“颜色选项”等信息；如果是一个“文章”模块，你可能想添加“文章作者”、“来源链接”或“阅读时长”等属性。这些根据特定业务需求而添加的额外信息，就是自定义参数字段。它让每一条内容的数据结构更加完整，也为前端展示提供了更多维度。

如何在安企CMS后台创建自定义参数字段？

创建自定义参数字段的过程非常直观，它与内容模型的管理紧密相连。

  1. 进入内容模型管理： 首先，登录安企CMS后台，通过左侧导航栏进入“内容管理”部分，然后点击“内容模型”。在这里，你会看到系统内置的“文章模型”、“产品模型”，以及你可能已经创建的其他自定义模型。

  2. 选择或创建内容模型： 选择你想要添加自定义字段的内容模型（例如“产品模型”），点击其右侧的“编辑”按钮。如果你需要为一种全新的内容类型设置字段，则可以点击“添加新模型”来创建一个新的内容模型。

  3. 配置自定义字段： 在内容模型的编辑界面，向下滚动找到“内容模型自定义字段”区域。这里就是我们定义各种个性化字段的地方。点击“添加字段”，会出现一个配置表单：

    • 参数名：这是字段在后台界面和前端模板中用于识别的中文名称，例如“产品价格”、“文章作者”。
    • 调用字段：这是在数据库和模板中实际引用的字段标识符，建议使用英文字母，如“productPrice”、“author”。这个字段名至关重要，它将是你在前端模板中获取该参数的唯一凭证。
    • 字段类型：根据你希望存储的数据类型选择合适的类型，安企CMS提供了多种选择，包括：
      • 单行文本：适用于短文本输入，如作者名、品牌名。
      • 数字：仅限输入数字，如库存、价格。
      • 多行文本：适用于较长的文本内容，如产品特性描述、简要介绍。
      • 单项选择/多项选择/下拉选择：用于预设选项，让用户从固定列表中选择，例如产品颜色、尺寸等。
    • 是否必填：勾选此项，发布内容时该字段必须填写。
    • 默认值：为字段设置一个初始值，如果用户未填写，则会使用此默认值。对于选择类型的字段，默认值需一行一个地输入选项内容。

    完成配置后，点击“确定”保存。重复此步骤可以添加多个自定义字段。

  4. 关联到文档编辑： 一旦自定义字段在内容模型中设置完毕，当你进入“内容管理”下的“发布文档”或编辑现有文档时，选择对应的分类（该分类所属模型需包含你自定义的字段），在文档编辑页面的“其他参数”折叠区域中，就会看到你刚刚定义的自定义参数字段。此时，你就可以为每篇文档填写这些专属信息了。

在前端模板中获取和显示自定义参数字段

定义好自定义参数字段后，下一步就是如何在你的网站前端模板中将这些信息展示出来。安企CMS提供了灵活的模板标签，让我们能够方便地获取这些数据。

安企CMS的模板语法类似Django，变量使用双花括号 {{变量名}} 包裹，标签则使用 {% 标签名 参数 %}。

  1. 使用 archiveDetail 标签获取单个自定义字段

    当你明确知道自定义字段的“调用字段名”，并且只需要获取当前文档的该字段值时，archiveDetail 标签是最直接的选择。

    • 基本用法： 
      
{% archiveDetail with name="自定义字段的调用字段名" %}
      例如，你为“文章模型”定义了一个“文章作者”字段，其“调用字段”为 author： 
      
<div>文章作者：{% archiveDetail with name="author" %}</div>
    • 获取多值字段（如图片组）： 如果你的自定义字段类型是图片组，它会返回一个图片URL的数组。你需要将其赋值给一个变量，然后通过 for 循环遍历显示： 假设你定义了一个“产品图片”字段，调用字段为 product_images： 
      
{% archiveDetail productImages with name="product_images" %}
<div class="product-gallery">
    {% for imgUrl in productImages %}
        <img src="{{ imgUrl }}" alt="产品图片" />
    {% endfor %}
</div>
    • 处理Markdown格式内容： 如果你的自定义字段类型是多行文本，并且你希望其内容支持Markdown格式并渲染为HTML，你需要结合 render 和 safe 过滤器： 假设你有一个“详细介绍”字段，调用字段为 details_markdown： 
      
<div class="product-details">
    {% archiveDetail detailsContent with name="details_markdown" %}
    {{ detailsContent|render|safe }}
</div>
      |render 过滤器负责将 Markdown 文本解析为 HTML，而 |safe 则告诉模板引擎这段 HTML 是安全的，不需要进行二次转义。

  2. 使用 archiveParams 标签获取所有自定义字段

    当你不确定有哪些自定义字段，或者你希望以通用方式遍历显示文档的所有自定义参数时，archiveParams 标签非常有用。它能获取当前文档或指定文档的所有自定义参数。

    • 获取有序列表（默认行为或 sorted=true）： archiveParams 默认返回一个有序的数组，每个数组项是一个包含 Name（参数名）和 Value（参数值）的对象。 
      
{% archiveParams params %}
<ul class="product-specs">
    {% for item in params %}
    <li>
        <span>{{ item.Name }}：</span>
        <span>{{ item.Value }}</span>
    </li>
    {% endfor %}
</ul>
{% endarchiveParams %}
      这种方式非常适合在产品详情页等场景，以列表形式展示所有自定义参数。你也可以在循环中根据 item.Name 进行条件判断，对特定字段做特殊处理。
    • 获取无序Map对象（sorted=false）： 如果你更喜欢通过键名直接访问，可以将 sorted 参数设置为 false，此时 archiveParams 会返回一个Map对象。 “`twig {% archiveParams params with sorted=false %}
      {% if params.productPrice %} {# 判断字段是否存在 #}
      价格：{{ params.productPrice.Value }}
      {% endif %} {% if params.stockQuantity