django-htmx

Django HTMX

使用 HTMX，在添加有针对性的局部页面更新时，仍由 Django 模板、视图、表单、权限和服务器端验证掌控。优先使用纯 Django，然后仅添加能改进工作流的最少 HTMX 行为。

在生成的 django-saas-starter 项目中：

• 已安装 django-htmx，且 django_htmx.middleware.HtmxMiddleware 会添加 request.htmx。
• htmx.min.js 会从 npm 复制到 frontend/static/vendors/js/，并由 frontend/templates/base_app.html 和 frontend/templates/base_landing.html 加载。
• 基础模板已在 htmx:configRequest 期间添加 X-CSRFToken，并设置 window.htmx.config.historyRestoreAsHxRequest = false。请勿在功能模板中重复此配置。
• 仅对菜单、模态框、展开状态和轻量过渡等浏览器本地状态使用 Alpine.js。

框架无关的 HTMX 技能

使用这些技能深入了解 htmx，然后将其应用到 Django 表单、 视图、模板、权限和测试中：

• htmx-endpoint-design：了解请求/响应契约、目标、交换、 带外更新和事件。
• htmx-recipes：了解实时搜索、分页、无限滚动、轮询、 对话框、点击编辑、增强链接和其他常见模式。
• htmx-security：了解 XSS、净化、CSP、CSRF 和 htmx 历史缓存风险。
• htmx-realtime：了解轮询、SSE 和 WebSocket 的权衡。
• htmx-interactivity：了解 Alpine.js 协作、事件边界，以及可替换目标之外的本地状态。
• htmx-js-api：了解编程式请求、htmx.process 和事件连接。

资源路由

仅加载当前任务所需的文件：

需求	阅读
Django 视图分支、响应辅助函数、表单、验证	references/django-view-patterns.md
模板目标、交换、带外更新、Alpine 事件、模式说明	references/template-interaction-patterns.md
安全规则、Django 测试、响应断言、参考文档	references/testing-security.md

实现工作流

1. 找出服务器状态的所有者：模型、查询集、表单、服务、权限或会话值。
2. 选择范围最小的 URL 边界：
   • 如果完整页面和局部内容共用相同的查询与权限，则复用现有视图，并通过 request.htmx 分支处理。
   • 如果交互具有范围较窄的组件契约或不同的变更规则，则创建专用端点。
3. 将可复用片段放在局部模板中，通常位于 frontend/templates/<app>/partials/... 或本地应用模板文件夹中。
4. 完整页面通过包含同一局部模板进行渲染，该模板也由 HTMX 响应返回。
5. 在可行时，为链接和表单保留非 HTMX 回退行为。
6. 如果视图根据 request.htmx 分支，则为常规请求和 HTMX 请求都添加测试。

Django 规则

• 只有在执行过相同的身份验证、权限检查和数据加载流程后，才能根据 request.htmx 分支处理。
• 对于同一 URL 会根据请求返回完整页面或局部内容的可缓存视图，使用 @vary_on_headers("HX-Request")。
• 优先使用 django_htmx.http 辅助工具，而不是手动编写 HTMX 标头： HttpResponseClientRedirect、HttpResponseClientRefresh、 HttpResponseLocation、HttpResponseStopPolling、push_url()、 replace_url()、retarget()、reswap()、reselect() 和 trigger_client_event()。
• 将 Django 表单作为验证的唯一事实来源。即使已配置基础 HTMX 标头，也要在表单中加入 {% csrf_token %}。
• 对于无效的 HTMX 表单提交，返回渲染后的已绑定表单，并使用常规状态码 200，除非项目明确处理 4xx 或 422 交换。
• 对于破坏性操作，要求使用 POST，除非项目有经过规划的 DELETE 方法覆盖模式。
• 明确划分所有权：HTMX 负责服务端请求、最新 HTML、历史记录更新和跨组件的服务端事实；Alpine 负责纯本地状态、键盘和菜单行为、临时 UI 状态及过渡效果。
• 仅当新状态值得拥有真实的浏览器 URL 时，才使用 hx-push-url="true"；并确保直接加载或刷新时，推送的 URL 能呈现完整页面。

避免

• 除非非 HTMX API 确实需要 JSON，否则不要为 UI 更新返回 JSON。
• 对于常规局部更新，不要添加 React、Vue 或客户端路由器。
• 不要在模板或浏览器事件处理程序中放置业务逻辑。
• 不要创建一个根据任意请求参数切换行为的通用“htmx endpoint”。请使用明确的 URL 和视图。
• 不要在没有防抖、节流或明确停止条件的情况下添加 hx-trigger="keyup" 或轮询。
• 不要使用 HTMX 绕过 Django 常规的身份验证、授权、CSRF、表单或消息处理模式。