alpinejs-django

使用 Django 的 Alpine.js

此技能适用于 Django 渲染模板中的本地浏览器状态：下拉菜单、模态框、标签页、展开面板、内联筛选器、禁用／加载状态、小型预览交互和仅客户端切换。对于需要持久化的状态，请以 Django 视图／表单／模型为准。服务器需要返回新 HTML 时，请使用 HTMX。

设置检查

• 确认项目如何加载 Alpine。优先以现有静态资源或打包流程为准。
• 找到加载 HTMX、Alpine 和应用 JavaScript 的基础模板、布局或打包入口点。除非有意更改初始化方式，否则请保留当前顺序。
• 确定已加载的 Alpine 文件是自动启动版还是模块版。如果项目已加载自动启动版 Alpine，请勿调用 Alpine.start()。如果使用模块版，请从负责的入口点注册组件并启动 Alpine。
• 简单的 Alpine 行为通常应使用 x-data 直接写在 Django 模板中。
• 如果值得提取可复用组件或存储，请在 Alpine 启动前注册。依赖应用级脚本中的 document.addEventListener("alpine:init", ...) 前，请检查现有脚本顺序。
• 需要注册可复用 Alpine 组件时，请添加或复用一个在 Alpine 启动前运行的脚本或入口点。在 document.addEventListener("alpine:init", ...) 中注册组件和存储，通过项目的常规资源路径引入该文件，并避免重复启动 Alpine。

归属规则

• Django 负责持久化、授权、验证、重定向和 HTML 渲染。
• HTMX 负责服务器往返请求和 DOM 交换。
• Alpine 负责浏览器中已有的临时状态。
• 普通 JavaScript 模块或打包入口点负责不适合限定在单个 Alpine 组件中的共享 DOM 行为。
• 请勿在 Alpine 和普通 JS 模块中重复实现同一行为。

模板模式

在所控制的标记附近使用简洁的 x-data 对象：

<div
  x-data="{ open: false }"
  @keydown.escape.window="open = false"
  @click.outside="open = false"
>
  <button
    type="button"
    :aria-expanded="open.toString()"
    @click.stop="open = !open"
  >
    Menu
  </button>

  <div x-cloak x-show="open" x-transition>
    ...
  </div>
</div>

优先使用 Alpine 指令，而不是手动操作 DOM：

• 使用 x-show 切换可见性，同时让元素保留在 DOM 中。
• 当元素应被创建和销毁时，在 <template> 上使用 x-if。
• 使用 x-model 管理仅客户端的输入状态；Django 表单提交和验证仍在服务器上进行。
• 使用 :class、:disabled、:aria-expanded 和 :hidden 设置由状态决定的属性。
• 使用 $watch 处理一个明确命名的状态转换；仅当依赖集合简单且有意为之时才使用 x-effect。
• 使用 $dispatch 在 Alpine 组件之间或从 Alpine 向 HTMX 触发器发送浏览器事件。

默认隐藏的内容请使用 x-cloak。确保基础 CSS 包含所需的 [x-cloak] { display: none !important; } 规则。

Django 数据

尽可能避免在复杂 JavaScript 表达式中插入 Django 模板变量。

对于简单值，优先使用 HTML 属性：

<div
  data-initial-label="{{ object.name }}"
  x-data="{ label: '' }"
  x-init="label = $el.dataset.initialLabel"
>
  <span x-text="label"></span>
</div>

对于结构化值，优先使用 Django 的 json_script，并在 x-init 中解析：

{{ rows|json_script:"rows-data" }}

<div
  x-data="{ rows: [] }"
  x-init="rows = JSON.parse(document.getElementById('rows-data').textContent)"
>
  <template x-for="row in rows" :key="row.id">
    <span x-text="row.name"></span>
  </template>
</div>

避免在 Alpine 表达式中使用 |safe。如果浏览器需要显示文本，请使用 x-text。仅对可信且已清理的 HTML 使用 x-html；大多数 HTML 应由 Django 渲染或通过 HTMX 返回。

Alpine 与 HTMX

当 HTMX 交换包含 x-data 的片段时，Alpine 应自动初始化新组件。HTMX 交换后请勿重新启动 Alpine。

将持久的 Alpine 状态放在将被替换的 HTMX 目标之外：

<section x-data="{ panelOpen: false }">
  <button type="button" @click="panelOpen = !panelOpen">Filters</button>

  <div id="results" hx-get="{% url 'search_results' %}" hx-trigger="change from:#filters">
    ...
  </div>
</section>

使用事件作为 HTMX 响应与 Alpine 状态之间的边界。在 Django 中设置 HX-Trigger 或 HX-Trigger-After-Swap 响应标头，然后在 Alpine 中监听：

<div x-data="{ open: true }" @profile-saved.window="open = false">
  <form hx-post="{% url 'profile_update' %}" hx-target="#profile-panel" hx-swap="outerHTML">
    ...
  </form>
</div>

请从 Alpine 中使用短横线格式监听 HTMX 生命周期事件，例如 @htmx:after-swap.window，因为 HTML 属性不区分大小写。

如果 Alpine 派发的事件需要由 HTMX 响应，请明确设置触发器：

<button type="button" x-data @click="$dispatch('refresh-results')">
  Refresh
</button>

<div hx-get="{% url 'results' %}" hx-trigger="refresh-results from:body">
  ...
</div>

无障碍

• 除非用于提交表单，否则应使用真正的 <button type="button"> 按钮。
• 将 ARIA 状态绑定到 Alpine 状态，尤其是 aria-expanded、 aria-controls、aria-selected 和 aria-hidden。
• 对可关闭的覆盖层支持 @keydown.escape.window。
• 对弹出框和菜单使用 @click.outside，并配备可见的触发器。
• 保留模态框、菜单和替换后的 HTMX 内容的焦点行为。如果需要焦点陷阱，请审慎添加专用的纯 JS 模块或 Alpine 插件，不要在属性中手动实现脆弱的焦点陷阱。

安全与 CSP

• 将所有 Alpine 表达式视为在用户浏览器中运行的 JavaScript。
• 除非用户有权查看，否则不要将机密、签名令牌或特权数据放入 x-data、 data-*、json_script 或隐藏输入中。
• 如果需要不含 unsafe-eval 的严格内容安全策略，请主动切换到 Alpine 的 CSP 构建版本，并重新测试 Alpine 表达式。默认的 alpinejs/dist/cdn.min.js 构建版本不是 CSP 构建版本。
• 如果 Alpine 代码发出 fetch() 请求，请添加 Django CSRF 标头，或改用现有的 HTMX/Django 表单。

验证

• 对于仅涉及模板的 Alpine 更改，运行覆盖该页面的 Django 模板或视图测试；如果 JavaScript 模块有更改，还要运行 npm run lint。
• 对于 HTMX 交互，同时测试完整页面和局部响应路径。
• 如果项目有前端构建步骤，请先运行构建，再依赖静态输出。
• 更改可见 UI 行为时，手动验证浅色和深色模式下的有状态控件。