htmx-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTMX Patterns for Django

Django的HTMX模式

Core Philosophy

核心理念

Server renders HTML, not JSON - HTMX requests return HTML fragments, not data
Partial templates for dynamic updates - separate
```
_partial.html
```
files for HTMX responses
Progressive enhancement - pages work without JavaScript, HTMX enhances UX
Minimal client-side complexity - let the server do the heavy lifting

服务器渲染HTML而非JSON——HTMX请求返回HTML片段而非数据
用于动态更新的局部模板——为HTMX响应单独创建
```
_partial.html
```
文件
渐进式增强——页面在无JavaScript时也能正常工作，HTMX提升用户体验
最小化客户端复杂度——让服务器承担主要工作

Critical Hints & Reminders

关键提示与注意事项

UX Best Practices

用户体验最佳实践

Always include loading indicators

Use
```
hx-indicator
```
to show loading states during requests
Users should never wonder if their action worked

Example:

<button hx-get="/data/" hx-indicator="#spinner">Load</button>

Always provide user feedback

Use Django messages framework for success/error feedback
Return error messages in HTMX responses, not silent failures
Show what happened after an action completes

Handle errors gracefully

Return proper HTTP status codes (400 for validation errors, 500 for server errors)
Render form errors in partial templates
Don't swallow exceptions - log and show user-friendly messages

始终添加加载指示器

使用
```
hx-indicator
```
在请求过程中显示加载状态
绝不能让用户疑惑自己的操作是否生效

示例：

<button hx-get="/data/" hx-indicator="#spinner">加载</button>

始终提供用户反馈

使用Django消息框架提供成功/错误反馈
在HTMX响应中返回错误信息，而非静默失败
操作完成后告知用户结果

优雅处理错误

返回正确的HTTP状态码（验证错误用400，服务器错误用500）
在局部模板中渲染表单错误
不要隐藏异常——记录并显示用户友好的提示信息

Django-Specific Patterns

Django专属模式

Always detect HTMX requests

Check
```
request.headers.get("HX-Request")
```
to detect HTMX requests
Return partial templates for HTMX, full page templates otherwise

Pattern:

if request.headers.get("HX-Request"): return render(request, "_partial.html", context)

Always return partials for HTMX

HTMX requests should return
```
_partial.html
```
templates, not full pages with
```
base.html
```
Full page responses to HTMX requests break the UX and send duplicate HTML
Partials should be self-contained HTML fragments

Always validate request.method

Check
```
request.method == "POST"
```
before processing form data
Return proper status codes (405 Method Not Allowed for wrong methods)

CSRF is already configured globally

The base template has
```
hx-headers
```
on
```
<body>
```
- no need to add CSRF tokens to individual forms
All HTMX requests automatically include the CSRF token

始终检测HTMX请求

通过
```
request.headers.get("HX-Request")
```
检测HTMX请求
对HTMX请求返回局部模板，否则返回完整页面模板

模式示例：

if request.headers.get("HX-Request"): return render(request, "_partial.html", context)

始终为HTMX返回局部模板

HTMX请求应返回
```
_partial.html
```
模板，而非包含
```
base.html
```
的完整页面
对HTMX请求返回完整页面会破坏用户体验并发送重复HTML
局部模板应是独立的HTML片段

始终验证request.method

处理表单数据前检查
```
request.method == "POST"
```
返回正确的状态码（请求方法错误时返回405 Method Not Allowed）

CSRF已全局配置

基础模板的
```
<body>
```
标签上已设置
```
hx-headers
```
——无需为单个表单添加CSRF令牌
所有HTMX请求会自动包含CSRF令牌

Template Organization

模板组织

Naming convention

Partials:
```
_partial.html
```
(underscore prefix)
Full pages:
```
page.html
```
(no prefix)
Example:
```
posts/list.html
```
(full page) includes
```
posts/_list.html
```
(partial)

Structure

Full page template extends
```
base.html
```
and includes partial
Partial contains only the dynamic HTML fragment
HTMX targets the partial's container div

Keep partials focused

Each partial should represent one logical UI component
Avoid partials that are too large or do too much
Compose larger UIs from multiple smaller partials

命名规范

局部模板：
```
_partial.html
```
（以下划线开头）
完整页面：
```
page.html
```
（无下划线前缀）
示例：
```
posts/list.html
```
（完整页面）包含
```
posts/_list.html
```
（局部模板）

结构

完整页面模板继承
```
base.html
```
并包含局部模板
局部模板仅包含动态HTML片段
HTMX定位到局部模板的容器div

保持局部模板聚焦

每个局部模板应代表一个逻辑UI组件
避免局部模板过大或功能过多
由多个小型局部模板组合成更大的UI

Django View Patterns

Django视图模式

HTMX Detection

HTMX检测

Check the

HX-Request

header to detect HTMX requests:

python

def my_view(request):
    context = {...}

    if request.headers.get("HX-Request"):
        return render(request, "app/_partial.html", context)

    return render(request, "app/full_page.html", context)

通过

HX-Request

头检测HTMX请求：

python

def my_view(request):
    context = {...}

    if request.headers.get("HX-Request"):
        return render(request, "app/_partial.html", context)

    return render(request, "app/full_page.html", context)

Form Handling Pattern

表单处理模式

Key points:

Validate form normally
On success: return partial with new data OR trigger client-side event
On error: return partial with form errors
Always handle both HTMX and non-HTMX cases

python

def create_view(request):
    if request.method == "POST":
        form = MyForm(request.POST)
        if form.is_valid():
            obj = form.save()
            if request.headers.get("HX-Request"):
                return render(request, "app/_item.html", {"item": obj})
            return redirect("app:list")

        # Return form with errors
        if request.headers.get("HX-Request"):
            return render(request, "app/_form.html", {"form": form})
    else:
        form = MyForm()

    return render(request, "app/create.html", {"form": form})

核心要点：

正常验证表单
成功时：返回包含新数据的局部模板，或触发客户端事件
错误时：返回包含表单错误的局部模板
始终同时处理HTMX和非HTMX请求

python

def create_view(request):
    if request.method == "POST":
        form = MyForm(request.POST)
        if form.is_valid():
            obj = form.save()
            if request.headers.get("HX-Request"):
                return render(request, "app/_item.html", {"item": obj})
            return redirect("app:list")

        # 返回带错误的表单
        if request.headers.get("HX-Request"):
            return render(request, "app/_form.html", {"form": form})
    else:
        form = MyForm()

    return render(request, "app/create.html", {"form": form})

Response Headers Reference

响应头参考

HTMX respects special response headers for client-side behavior:

HTMX会遵循特殊的响应头以实现客户端行为：

HX-Trigger

Trigger client-side events after response

Use case: Update other parts of page after action
Example:
```
response["HX-Trigger"] = "itemCreated"
```

Template listens:

<div hx-get="/count/" hx-trigger="itemCreated from:body">

操作完成后触发客户端事件

适用场景：操作完成后更新页面其他部分
示例：
```
response["HX-Trigger"] = "itemCreated"
```

模板监听：

<div hx-get="/count/" hx-trigger="itemCreated from:body">

HX-Redirect

Client-side redirect

Use case: Redirect after successful action

Example:

response["HX-Redirect"] = reverse("app:detail", args=[obj.pk])

客户端重定向

适用场景：操作成功后重定向

示例：

response["HX-Redirect"] = reverse("app:detail", args=[obj.pk])

HX-Retarget / HX-Reswap

Override hx-target and hx-swap from server

Use case: Different targets for success vs error
Success:
```
response["HX-Retarget"] = "#main"
```
Error: Return partial without changing target (targets the form)

从服务器端覆盖hx-target和hx-swap

适用场景：成功与错误场景使用不同的目标
成功时：
```
response["HX-Retarget"] = "#main"
```
错误时：返回局部模板而不修改目标（目标为表单）

HX-Refresh

Force full page refresh

Use case: Major state change that affects whole page
Example:
```
response["HX-Refresh"] = "true"
```

强制全页面刷新

适用场景：影响整个页面的重大状态变更
示例：
```
response["HX-Refresh"] = "true"
```

Common Pitfalls

常见陷阱

Missing loading indicators: Always use
```
hx-indicator
```
- users click multiple times without feedback
Full pages in HTMX responses: Return
```
_partial.html
```
, not full pages with
```
base.html
```
- check
```
HX-Request
```
header
Not handling form errors: Always return the form with errors on validation failure, not just the success case
Not disabling buttons: Use
```
hx-disabled-elt="this"
```
to prevent duplicate submissions
N+1 queries: HTMX views need
```
select_related()
```
/
```
prefetch_related()
```
just like regular views

缺少加载指示器：始终使用
```
hx-indicator
```
——用户在无反馈时会多次点击
HTMX响应返回完整页面：返回
```
_partial.html
```
而非包含
```
base.html
```
的完整页面——务必检查
```
HX-Request
```
头
未处理表单错误：验证失败时务必返回带错误的表单，不能只处理成功场景
未禁用按钮：使用
```
hx-disabled-elt="this"
```
防止重复提交
N+1查询问题：HTMX视图和常规视图一样需要使用
```
select_related()
```
/
```
prefetch_related()
```

Integration with Other Skills

与其他技能的集成

django-templates: Partial template organization and inheritance patterns
django-forms: HTMX form submission and validation
django-extensions: Use
```
show_urls
```
to verify HTMX endpoints
pytest-django-patterns: Testing HTMX endpoints and headers
systematic-debugging: Debug HTMX request/response issues

django-templates：局部模板的组织与继承模式
django-forms：HTMX表单提交与验证
django-extensions：使用
```
show_urls
```
验证HTMX端点
pytest-django-patterns：测试HTMX端点与请求头
systematic-debugging：调试HTMX请求/响应问题