事件

用 on{Event}$ 注册懒加载事件，理解异步事件与声明式修饰符。

约 2 分钟Qwik v208 / 19

本页目录5 节

复用处理函数
异步事件的三条限制
passive 与 capture
window 与 document 事件
同步事件：sync$

事件用 on{EventName}$ 属性注册。$ 表示这里是一个懒加载边界：处理函数只有用户真正触发事件时才会下载。

tsxcode

<button onClick$={() => count.value++}>
  +1
</button>

01复用处理函数#

同一个函数要绑到多个元素时，用 $() 包成 QRL，再传给事件属性：

tsxcode

const increment = $(() => count.value++);

return (
  <>
    <button onClick$={increment}>+</button>
    <button onClick$={increment}>再来一次</button>
  </>
);

多个处理函数可以放进数组，按顺序执行：

tsxcode

<button onClick$={[logClick, increment, track]}>
  点击
</button>

LIVE / USE_SIGNALidle

这个数字由 signal 驱动。点击任意按钮，只有这块 DOM 更新。

02异步事件的三条限制#

Qwik 的事件处理是异步的：首次触发时，代码可能还在下载。因此事件对象上的这些 API 不可用：

event.preventDefault()
event.stopPropagation()
event.currentTarget

Qwik 用声明式属性替代前两个；currentTarget 作为处理函数的第二个参数传入。

tsx声明式修饰符

<a
  href="/docs"
  preventdefault:click
  stoppropagation:click
  onClick$={() => {
    // 不要在这里调用 event.preventDefault()
  }}
>
  打开文档
</a>

处理函数的签名是 (event, element)。需要当前元素时用第二个参数：

tsxcode

<input
  onInput$={(_, input) => {
    query.value = input.value;
  }}
/>

03passive 与 capture#

滚动、触摸等高频事件可以标记为 passive，让浏览器跳过等待处理函数的步骤。需要在捕获阶段执行时，用 capture:eventname：

tsxcode

<div passive:touchmove onTouchMove$={() => {}} />
<div capture:click onClick$={() => {}} />

04window 与 document 事件#

全局事件用 window:on* 与 document:on* 前缀。它们同样保持懒加载，并在组件销毁时自动清理：

tsxcode

<div
  window:onScroll$={() => {
    scrolled.value = true;
  }}
  document:onKeyDown$={(event) => {
    if (event.key === 'Escape') close();
  }}
/>

在可复用的 hook 中无法写 JSX 时，用 useOn()、useOnWindow()、useOnDocument()，回调同样要用 $() 包装。

05同步事件：sync$#

极少数场景必须在事件分发阶段同步执行，例如在浏览器原生行为发生前读取选区。sync$() 可以把一段代码内联进 HTML，代价是失去懒加载：

tsxcode

import { sync$ } from '@qwik.dev/core';

<button
  onClick$={sync$((event) => {
    event.preventDefault();
  })}
/>;