htmx-universal-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

HTML over JSON: The server MUST respond with HTML fragments (partials), not JSON.
Side Effects via HTML: Do not use client-side logic to update the DOM. Let the server response dictate changes via
```
hx-swap
```
.

CSRF Protection: HTMX requests are non-idempotent (POST/PUT/DELETE) and require CSRF protection just like standard forms.
- Header Method: Configure the global
```
hx-headers
```
  to include the token:
```
<body hx-headers='{"X-CSRF-Token": "{{ csrfToken }}"}'>
```
  .
- Form Method: If headers aren't viable, ensure every
```
<form>
```
  includes the hidden CSRF input.
XSS Prevention: Since we are injecting HTML, ensure all user content rendered on the server is strictly escaped before reaching the client.

CSRF防护：HTMX的非幂等请求（POST/PUT/DELETE）需要像标准表单一样进行CSRF防护。
- 头部方法：配置全局
```
hx-headers
```
  以包含令牌：
```
<body hx-headers='{"X-CSRF-Token": "{{ csrfToken }}"}'>
```
  。
- 表单方法：如果无法使用头部，确保每个
```
<form>
```
  都包含隐藏的CSRF输入字段。
XSS防护：由于我们会注入HTML，确保所有在服务器渲染的用户内容在发送到客户端前都经过严格转义。

The "Partial" Rule: Identify strictly which part of the UI needs updating. Create a server route that renders only that component.
Idempotency: GET requests should never change state. Use POST/PUT/PATCH/DELETE for actions.
Progressive Enhancement: Design the feature to work with standard HTML forms/links first where possible.

Request Indicators: ALWAYS use

hx-indicator

Pattern:

<button hx-post="..." hx-indicator="#loading-spinner">Save</button>

Active States: Use the
```
htmx-added
```
class or
```
hx-vals
```
to manage active states via server rendering.

请求指示器：务必使用

hx-indicator

。

示例：

<button hx-post="..." hx-indicator="#loading-spinner">保存</button>

The backend must communicate status via HTTP Codes:

200 OK: Swap content normally.
204 No Content: Do nothing.
422 Unprocessable Entity: Validation error. Swap the form with the HTML containing error messages.
HX-Retarget: Use this header if an error requires updating a global element (like a top-level alert) instead of the local target.

后端必须通过HTTP状态码传递状态：