作为一位深谙AnQiCMS运作的网站运营人员，我非常理解在网站中提供用户互动渠道的重要性。用户留言表单是收集反馈、解答疑问、建立用户关系的关键工具。在AnQiCMS中，通过其灵活的模板引擎，嵌入和展示留言表单是一个直接且可高度定制的过程。本文将详细阐述如何在AnQiCMS模板中实现这一功能。
理解留言表单的核心机制
AnQiCMS内置了网站留言管理功能，并提供了专门的模板标签guestbook来帮助我们构建前端留言表单。这个标签的作用是动态地获取后台配置的留言字段，让我们能够灵活地在模板中渲染出用户友好的表单。
在使用guestbook标签时，我们通常会将其包裹在一个HTML <form>元素中。表单的提交地址固定为/guestbook.html，并且必须使用POST方法。表单中需要包含一些核心字段，例如user_name（留言者姓名）、contact（联系方式）和content（留言内容）。除了这些默认字段，AnQiCMS还支持在后台自定义额外的留言字段，这些自定义字段也会通过guestbook标签动态地提供给我们。
嵌入留言表单到模板中
要将留言表单嵌入到网站模板中，我们首先需要创建一个用于展示留言的模板文件。根据AnQiCMS的模板约定，留言表单页面通常存放在模板目录的guestbook/index.html文件中。如果您的主题模板采用扁平化模式，则可以是guestbook.html。
在该模板文件中，我们将利用guestbook标签来遍历后台配置的所有留言字段，并根据字段类型动态生成相应的HTML表单元素。以下是一个完整的示例代码段，它演示了如何构建一个能够适应后台配置的动态留言表单：
<form method="post" action="/guestbook.html">
<input type="hidden" name="return" value="html"> {# 可选：指定后台返回HTML格式，也可设置为json #}
{% guestbook fields %}
{% for item in fields %}
<div class="form-group">
<label for="{{ item.FieldName }}">{{ item.Name }}：</label>
<div>
{% if item.Type == "text" or item.Type == "number" %}
<input type="{{ item.Type }}" name="{{ item.FieldName }}" id="{{ item.FieldName }}"
{% if item.Required %}required{% endif %}
placeholder="{{ item.Content }}" autocomplete="off" class="form-control">
{% elif item.Type == "textarea" %}
<textarea name="{{ item.FieldName }}" id="{{ item.FieldName }}"
{% if item.Required %}required{% endif %}
placeholder="{{ item.Content }}" rows="5" class="form-control"></textarea>
{% elif item.Type == "radio" %}
{% for val in item.Items %}
<label class="radio-inline">
<input type="radio" name="{{ item.FieldName }}" value="{{ val }}"
{% if loop.first and item.Required %}checked{% endif %}> {{ val }}
</label>
{% endfor %}
{% elif item.Type == "checkbox" %}
{% for val in item.Items %}
<label class="checkbox-inline">
<input type="checkbox" name="{{ item.FieldName }}[]" value="{{ val }}"> {{ val }}
</label>
{% endfor %}
{% elif item.Type == "select" %}
<select name="{{ item.FieldName }}" id="{{ item.FieldName }}" class="form-control">
{% for val in item.Items %}
<option value="{{ val }}">{{ val }}</option>
{% endfor %}
</select>
{% endif %}
</div>
</div>
{% endfor %}
{% endguestbook %}
{# 验证码区域，如果后台开启了验证码，这里是必须的 #}
<div class="form-group captcha-area">
<label for="captcha">验证码：</label>
<div class="input-group">
<input type="hidden" name="captcha_id" id="captcha_id">
<input type="text" name="captcha" id="captcha" required placeholder="请输入验证码" class="form-control">
<span class="input-group-btn">
<img src="" id="get-captcha" alt="验证码" class="captcha-img" style="cursor: pointer;">
</span>
</div>
</div>
<div class="form-group">
<button type="submit" class="btn btn-primary">提交留言</button>
<button type="reset" class="btn btn-default">重置</button>
</div>
</form>
{# 验证码刷新JS #}
<script>
document.addEventListener('DOMContentLoaded', function() {
const getCaptchaBtn = document.getElementById('get-captcha');
const captchaIdField = document.getElementById('captcha_id');
function fetchCaptcha() {
fetch('/api/captcha')
.then(response => response.json())
.then(res => {
if (res.code === 0 && res.data) {
captchaIdField.value = res.data.captcha_id;
getCaptchaBtn.src = res.data.captcha;
} else {
console.error('获取验证码失败:', res.msg);
}
})
.catch(err => console.error('获取验证码请求失败:', err));
}
if (getCaptchaBtn) {
getCaptchaBtn.addEventListener('click', fetchCaptcha);
fetchCaptcha(); // 页面加载时自动获取一次验证码
}
});
</script>
在上面的代码中，guestbook fields标签会循环遍历后台配置的每个留言字段。对于每个item（字段），我们可以访问其Name（字段显示名称）、FieldName（表单提交时的字段名）、Type（字段类型）、Required（是否必填）和Content（默认值或placeholder）。根据Type的不同，我们生成了不同的HTML输入元素，如文本框、数字输入框、多行文本域、单选框、复选框和下拉选择框。item.Items属性用于单选、多选和下拉选择类型，它包含了所有可选项。
值得注意的是，Required属性被转换为HTML的required属性，以确保用户在提交前填写了必填信息。return隐藏字段用于告知服务器期望的响应格式，默认为html，也可以设为json以方便前端进行异步处理。
整合留言验证码（可选）
为了防止垃圾信息和机器人提交，AnQiCMS提供了留言验证码功能。如果您在后台开启了此功能，那么在前端模板中嵌入验证码就变得至关重要。
首先，请确保您已在AnQiCMS后台的留言设置中启用了验证码。
其次，您需要在留言表单中添加验证码相关的HTML结构和JavaScript代码。上述代码示例中已包含了这部分内容，具体来说：
一个隐藏的input字段用于存放验证码的ID (captcha_id)。
一个文本input字段用于用户输入验证码 (captcha)。
一个img标签用于显示验证码图片，其src属性会通过JavaScript动态加载。
配套的JavaScript代码会在页面加载时自动请求并显示验证码，并在用户点击验证码图片时刷新验证码。验证码图片通过fetch('/api/captcha')接口获取，该接口会返回captcha_id和captcha图片URL。
表单提交与用户体验
当用户填写并提交表单后，数据会发送到/guestbook.html。AnQiCMS后台会接收并处理这些数据，包括执行验证码校验、保存留言到数据库、以及可能触发的邮件通知等（如果后台配置了邮件提醒）。
成功提交后，如果return字段设置为html，服务器可能会重定向回留言页面并显示一条成功消息；如果设置为json，前端可以通过JavaScript处理返回的JSON数据，例如弹出一个提示框，或者清空表单。在设计前端用户体验时，考虑到表单提交后的反馈是十分重要的，这能让用户清楚地知道他们的操作是否成功。
通过上述步骤和代码示例，您应该能够在AnQiCMS模板中成功嵌入并显示一个功能完善的用户留言表单，为网站的用户互动提供一个稳固的基础。
常见问题解答 (FAQ)
1. 如何自定义留言表单字段的样式和布局？ 您可以通过两种主要方式自定义留言表单的样式和布局：
- CSS样式定制：在上述代码示例中，表单元素使用了基本的HTML结构。您可以根据您的网站主题和设计需求，为
div.form-group、label、input、textarea以及按钮等元素添加自定义的CSS类（例如form-control、btn），然后在您的主题CSS文件中定义这些类的样式。 - HTML结构调整：
guestbook标签主要用于动态生成输入字段本身。您可以在{% for item in fields %}循环内部，根据item.FieldName或item.Type进行更细致的条件判断，从而为特定的字段应用不同的HTML包裹结构，例如将其放入不同的div中以实现多列布局，或者为特定字段添加额外说明文字。
2. 我可以在留言表单中添加非AnQiCMS后台配置的额外字段吗？
不建议直接在前端模板中添加非AnQiCMS后台配置的额外字段。AnQiCMS的guestbook标签旨在与后台的留言字段管理功能协同工作，确保提交的数据能够被系统正确识别和存储。如果您添加了未经后台配置的字段，这些字段的数据通常不会被AnQiCMS保存。
如果需要新增字段，最推荐的做法是在AnQiCMS后台的“功能管理” -> “网站留言管理”中，通过“自定义留言字段”功能进行配置。这样，这些字段就能被guestbook标签识别并自动渲染，并且其数据也能被后台正确处理和存储。
3. 用户提交留言后，网站如何向我发送通知？ AnQiCMS支持配置留言邮件提醒功能。您可以在后台的“功能管理”找到“邮件提醒管理”，在这里配置SMTP服务器信息以及接收留言通知的邮箱地址。一旦配置完成，当有用户通过网站的留言表单提交新留言时，系统就会自动发送邮件通知到您指定的邮箱，方便您及时处理用户反馈。