如何用HTMX在Django模态框渲染表单错误并保留当前页面？

核心问题 #

1. 如何通过HTMX在表单验证失败时，在当前页面（Bootstrap模态框内）渲染错误信息，避免页面跳转？
2. 表单已设置method="post"，是否需要保留HTMX的hx-post属性？

解决方案步骤 #

1. HTMX属性配置说明 #

• 必须添加hx-post属性：HTMX的hx-post会接管原生表单的提交行为，实现异步请求。原生method="post"可以保留作为降级方案（当HTMX失效时，表单仍能通过原生方式提交），不影响HTMX的正常工作。
• 额外添加两个关键属性：
  • hx-target="#login-form-container"：指定验证失败后，用返回的HTML替换哪个容器的内容
  • hx-swap="innerHTML"：设置替换方式为覆盖目标容器的内部HTML

2. 修改表单代码 #

将表单包裹在一个指定ID的容器内，添加HTMX属性：

<div id="login-form-container">
  <form class="row my-4 align-items-center" method="post"
        hx-post="{% url 'accounts:login' %}"
        hx-target="#login-form-container"
        hx-swap="innerHTML">
    {% csrf_token %}
    {{ login_form.as_p }}
    {% if login_form.errors %}
        <ul class="text-danger">
            {% for field_errors in login_form.errors.values %}
                {% for error in field_errors %}
                    <li>{{ error }}</li>
                {% endfor %}
            {% endfor %}
        </ul>
    {% endif %}
    <button type="submit" class="btn btn-primary">Ingresar</button>
  </form>
</div>

3. 调整视图代码 #

原视图返回JSON数据，HTMX无法直接渲染，需改为返回带错误信息的表单HTML片段；登录成功时通过HX-Redirect头触发页面跳转：

from django.shortcuts import render, redirect, HttpResponse
from django.contrib.auth import authenticate, login
from .forms import LoginForm

def login_view(request):
    if request.method == 'POST':
        login_form = LoginForm(request, data=request.POST)
        if login_form.is_valid():
            username = login_form.cleaned_data.get('username')
            password = login_form.cleaned_data.get('password')
            user = authenticate(request, username=username, password=password)
            if user is not None:
                login(request, user, backend='django.contrib.auth.backends.ModelBackend')
                # 登录成功后，通过HTMX响应头触发跳转
                response = HttpResponse()
                response['HX-Redirect'] = '/'
                return response
        # 验证失败，渲染带错误的表单片段返回
        return render(request, 'accounts/login_form_fragment.html', {'login_form': login_form})
    else:
        # GET请求返回空表单片段
        login_form = LoginForm(request)
        return render(request, 'accounts/login_form_fragment.html', {'login_form': login_form})

4. 创建表单片段模板 #

新建accounts/login_form_fragment.html，内容与上述表单容器代码完全一致，用于视图返回渲染后的表单。

5. 优化模态框加载逻辑 #

为确保每次打开模态框都加载最新表单，给触发链接添加HTMX加载属性：

<li class="user">
  <a data-bs-toggle="modal" data-bs-target="#loginModal" 
     hx-get="{% url 'accounts:login' %}" 
     hx-target="#login-form-container"
     href="#">Hello, sign in<i class="fa fa-user ps-2 text-primary"></i></a>
</li>

同时调整模态框结构，预留表单容器：

<div class="modal fade" id="loginModal" tabindex="-1" aria-labelledby="loginModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="loginModalLabel">登录</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
      </div>
      <div class="modal-body">
        <div id="login-form-container"></div>
      </div>
    </div>
  </div>
</div>

内容的提问来源于stack exchange，提问作者Omar Gonzales