组件 props、children 与序列化

Qwik 在服务端生成 HTML，并在浏览器需要交互时恢复组件。传入组件的 props、children 和可恢复状态必须能被序列化；闭包函数要用 $ 标记为可恢复的 QRL，不能把 DOM 节点、类实例或任意函数直接塞进状态。

从一个可交互组件开始

tsx

import { component$, useSignal } from '@builder.io/qwik'

export default component$(() => {
  const count = useSignal(0)
  return <button onClick$={() => count.value++}>count: {count.value}</button>
})

先查看服务端 HTML，再点击按钮并观察网络面板：首次 HTML 已有按钮文本，点击时浏览器才加载对应事件处理器。把 onClick$ 改成未序列化的普通函数会在构建或恢复阶段报错。

props、children 与边界

字符串、数字、布尔值、数组和普通对象可作为 props；函数必须经过 QRL 序列化。children 是组件内容的延迟边界，组件应保持单一职责，不在 props 中传递实时 DOM 引用。服务端和客户端生成相同初始标记，否则恢复会出现内容不一致。

异步数据要区分“服务端已序列化的初始值”和“浏览器交互后重新请求的值”。部署缓存若把旧 HTML 与新 chunk 混用，恢复可能找不到 QRL；发布时要保证资源版本一致。

练习

增加一个 label prop 与默认 children，并验证字符串可序列化。
把点击处理拆成 $ 函数，检查初始 HTML、事件 chunk 和计数变化。
故意传入 document.body 或类实例，记录失败位置，并改为传递可序列化 id。

查看本节答案