如何在 Qwik 中创建不可序列化的函数以避免自动序列化-js教程-PHP中文网

如何在 Qwik 中创建不可序列化的函数以避免自动序列化

本文详解如何使用 noserialize() 工具函数和 noserialize 类型标记，主动排除函数或对象的序列化行为，显著提升 qwik 应用的首屏加载与水合性能。

本文详解如何使用 noserialize() 工具函数和 noserialize 类型标记，主动排除函数或对象的序列化行为，显著提升 qwik 应用的首屏加载与水合性能。

在 Qwik 中，框架默认会对组件作用域内的闭包值（如函数、类实例、DOM 引用等）进行序列化，以便服务端渲染（SSR）后能在客户端正确“恢复”状态。但并非所有值都需要或适合序列化——例如仅用于日志、调试、第三方 SDK 回调或 DOM 操作的函数，若被序列化，不仅会增大 HTML 体积、拖慢传输，还可能因无法反序列化而报错。

Qwik 提供了明确的机制来声明“不可序列化”：noSerialize() 工具函数 和 NoSerialize 类型标记。二者配合使用，可精准控制序列化边界。

✅ 正确用法：noSerialize() + NoSerialize

noSerialize(value) 是一个运行时标记函数，它返回一个特殊代理对象（内部带有 QRL 元数据），告知 Qwik 构建器和序列化器：“此值无需序列化，客户端应重新创建或忽略”。同时，配合 TypeScript 的 NoSerialize 类型，可在编译期获得类型安全与 IDE 支持。

以下是一个优化后的示例，展示如何将搜索处理逻辑中无需跨 SSR 传递的副作用函数剥离：

import { 
  component$, 
  noSerialize, 
  type NoSerialize, 
  useSignal, 
  useNavigate,
  useStylesScoped$
} from '@builder.io/qwik';
import { SearchNormalIcon } from './icons';

// 声明不可序列化的函数类型（推荐用于 props 或 state）
type ProductFinderProps = {
  onSearchStart?: NoSerialize void>;
};

export const ProductFinder = component$<productfinderprops>(({ onSearchStart }) => {
  const product = useSignal<string>('');
  const nav = useNavigate();
  useStylesScoped$(styles);

  const handleSearch = $(async () => {
    // ✅ 场景1：临时不可序列化函数（仅当前作用域有效）
    const logSearch = noSerialize(() => {
      console.debug('[ProductFinder] Searching for:', product.value);
    });
    logSearch(); // 可直接调用，不参与序列化

    // ✅ 场景2：赋值给 signal —— 必须显式标注类型
    const searchTracker = useSignal<noserialize count: number lastquery: string>>(null);
    searchTracker.value = noSerialize({
      count: 0,
      lastQuery: product.value,
      increment() {
        this.count++;
      }
    });

    // ✅ 场景3：通过 props 接收不可序列化方法（需父组件传入已标记值）
    onSearchStart?.();

    if (product.value.trim()) {
      await nav(`/?page=1&categoryType=NEW&filter=${encodeURIComponent(product.value)}`);
    }
  });

  return (
    <div class="form">
      <input type="text" class="input" placeholder="Buscar productos" value="{product.value}" oninput> (product.value = (e.target as HTMLInputElement).value)}
      />
      <button class="button" onclick aria-label="Search">
        <searchnormalicon size="100%"></searchnormalicon></button>
    </div>
  );
});</noserialize></string></productfinderprops>

⚠️ 关键注意事项

不可序列化 ≠ 不可访问：noSerialize() 标记的值仅跳过序列化流程，仍可在客户端正常执行；但它不会从服务端传送到客户端，因此不能依赖其初始状态。
禁止在服务端渲染期间调用副作用函数：如 noSerialize(() => fetch(...)) 在 SSR 时不会执行（因为函数本身未被序列化），所有副作用应确保在客户端生命周期（如 useClientEffect$）中触发。
避免嵌套序列化陷阱：若将 noSerialize(fn) 赋值给一个未标注 NoSerialize 的 useSignal，TypeScript 会报错；务必同步使用 useSignal>。
不支持箭头函数直接作为 onClick$ 等 $ 函数参数：onClick$={noSerialize(() => {...})} ❌ 错误；必须通过 $() 包裹后再标记，或直接在 $() 内部调用 noSerialize()（如上例所示）。