v4 新纪元

<!-- 动词与路径分列：方法可来自别处，属性名不必跟着变 -->
<button hx-action="/clicked" hx-method="post" hx-swap="outerHTML">点我</button>

<!-- 按状态码分叉：422 改道、5xx 干脆不换 -->
<form hx-post="/register" hx-target="#result"
      hx-status:422="target:#errors select:#validation-errors"
      hx-status:5xx="swap:none">…</form>

<!-- 第三方组件不该被 htmx 碰：冻结它 -->
<custom-map hx-morph-skip></custom-map>

<!-- 主内容：照常换进 hx-target -->
<div class="echo-card"><h5>主响应已换入</h5></div>

<!-- 多路片段：各自带 hx-target 与 hx-swap -->
<hx-partial hx-target="#p-inbox" hx-swap="beforeend">
  <div class="echo-card">新消息</div>
</hx-partial>

<hx-partial hx-target="#p-badge" hx-swap="innerHTML">
  <span>7</span>
</hx-partial>

<section data-count="0">
  <button hx-on:click="data.count--">−1</button>
  <output hx-live:text="data.count">0</output>
  <button hx-on:click="data.count++">+1</button>
  <span hx-live:text="data.count % 2 === 0 ? '（偶数）' : '（奇数）'">（偶数）</span>
</section>

<!-- htmx 2：隐式继承，后代自动获得 -->
<div hx-target="#output" hx-headers='{"X-Token":"abc"}'>
  <button hx-get="/items">Load</button>
</div>

<!-- htmx 4：显式声明，一眼看出源头 -->
<div hx-target:inherited="#output" hx-headers:inherited='{"X-Token":"abc"}'>
  <button hx-get="/items">Load</button>
</div>

// htmx 2
document.addEventListener('htmx:configRequest', (evt) => {
  evt.detail.headers['X-Custom'] = 'value';
  evt.detail.parameters['key'] = 'value';
  evt.detail.path = '/modified-url';
});

// htmx 4
document.addEventListener('htmx:config:request', (evt) => {
  evt.detail.ctx.request.headers['X-Custom'] = 'value';
  evt.detail.ctx.request.body.set('key', 'value');   // FormData
  evt.detail.ctx.request.action = '/modified-url';
});

<!-- 精准分流：422 改道到错误区，5xx 干脆不换 -->
<form hx-post="/register" hx-target="#result"
      hx-status:422="target:#errors"
      hx-status:5xx="swap:none">…</form>

<!-- 全局恢复 htmx 2 的默认：4xx/5xx 不换入 -->
<meta name="htmx-config" content='{"noSwap": [204, 304, "4xx", "5xx"]}'>

// htmx 2
htmx.defineExtension('my-ext', {
  onEvent: function (name, evt) {
    if (name === 'htmx:configRequest') { /* … */ }
  },
  transformResponse: function (text, xhr, elt) { /* … */ }
});

// htmx 4
htmx.registerExtension('my-ext', {
  init(api) { /* 拿到内部 API 备用 */ },
  htmx_config_request(elt, detail) {
    detail.ctx.request.headers['X-Tag'] = 'my-ext';
  },
  htmx_after_request(elt, detail) {
    console.log('落幕', detail.ctx.request.action);
  }
});

npx htmx.org@4.0.0 upgrade-check -- ./path/to/project

# 默认只认 .html .php .js .ts .jinja .jinja2 .j2 .erb .hbs
npx htmx.org@4.0.0 upgrade-check --ext .vue ./path/to/project

<!-- 桥一：恢复 v2 的两项默认行为 -->
<meta name="htmx-config" content='{
    "implicitInheritance": true,
    "noSwap": [204, 304, "4xx", "5xx"]
}'>

<!-- 桥二：v2 的属性名与事件名在 v4 上继续可用 -->
<script src="/vendor/htmx.js"></script>
<script src="/vendor/ext/htmx-2-compat.js"></script>