@composy/shared-vue

@composy/shared-vue

Vue 3 适配包，提供 hooks、composables 和 Vue 工具函数。该包不复制核心算法， 需要优先复用 @composy/shared-core 暴露的工具、协议和类型。

能力范围

• hooks：useLocalStorage、useForm、useFetch、useModal、useToast、 useVirtualList、useWebSocket 等组合式函数。
• composables：无头选择器和响应式弹层组合能力。
• utils：withInstall、VNode 渲染、批量更新等 Vue 专属工具。
• types：Vue hook 与组件辅助类型。

Core 复用示例

useLocalStorage 与 useSessionStorage 只负责 Vue ref/watch/onUnmounted 桥接， 序列化、SSR 安全访问、异常隔离和函数式更新均复用 core storage 工具。

import { stringSerializer, useLocalStorage } from '@composy/shared-vue/hooks'

const [theme, setTheme, removeTheme] = useLocalStorage('theme', 'light', {
  serializer: stringSerializer,
})

setTheme(current => (current === 'dark' ? 'light' : 'dark'))
removeTheme()

异步请求约定

• useAsyncData 以最后一次调用为准：新请求会使旧请求结果失效，缓存可正确保存 0、false、空字符串等值；fetcher 的最后一个参数是 AbortSignal，可传给 fetch 等 API，让替换、手动取消和作用域销毁真正中止底层请求；被替换或取消的防抖调用会以 null 结束。
• usePagination 的 fetcher 可接收第二个 AbortSignal，useInfiniteScroll 的 fetcher 可接收第三个 AbortSignal；取消或刷新时，旧响应不会覆盖新数据。
• useAsyncValidator 同样只提交最新验证结果；预检查跳过时会清理旧错误并标记当前值有效。
• useFetch 会保留 FormData、Blob、URLSearchParams 等原生请求体，只对普通对象进行 JSON 序列化；可通过 signal 取消请求，beforeRequest 等待期间也会响应取消。

useAsyncData(async (userId: string, signal: AbortSignal) => {
  const response = await fetch(`/api/users/${userId}`, { signal })
  return response.json()
})

usePagination(async (params, signal) => {
  const response = await fetch(`/api/items?page=${params.page}`, { signal })
  return response.json()
})

const controller = new AbortController()
useFetch('/api/profile', { signal: controller.signal })
controller.abort()

观察器与图片懒加载

• useIntersectionObserver().reconnect() 会重建底层观察器并恢复原先登记的元素，不需要调用方重复执行 observe()。
• useLazyLoad() 会复用同一个 IntersectionObserver，目标元素变化或重复启动时不会叠加观察器。
• useImageLazyLoad().setSrc() 在图片请求切换期间会忽略旧请求的回调，避免旧 URL 覆盖新 URL 的加载状态。

开发约定

• hooks 内的纯逻辑优先下沉到 @composy/shared-core。
• useCache({ autoCleanup: true }) 会在 Vue effect scope 销毁时停止清理定时器；脱离 scope 使用时可显式调用返回的 dispose()。
• useAsyncMemoize() 会合并同一 key 的 pending Promise；invalidate() 或 clear() 后，旧请求完成 也不会把已失效的结果重新写回缓存。
• 组件卸载、事件监听、定时器和 observer 必须有清理路径。
• 测试 Vue DOM 行为时使用文件级 // @vitest-environment jsdom。
• 对 @composy/shared-core/* 的单测解析由根 vitest.config.ts 指向源码。

验证

pnpm --filter @composy/shared-vue typecheck
pnpm --filter @composy/shared-vue test:run
pnpm --filter @composy/shared-vue build

构建产物覆盖 dist/es/esm/lib。 ESM 声明中的相对模块路径会补齐 .js，可由 TypeScript NodeNext 消费端直接解析。