cabinet-fe/veltra-compositions

veltra-compositions

生成物

| 文件 | 内容 | | ------------------------------------------------------------ | -------------------------------------------- | | generated/modules/ | 每个 use-* 一篇，含该模块下全部 .ts 源码 | | generated/manifest.json | 同步时间与模块文件列表 | | references/usage-patterns.md | desktop 中的真实调用片段 |

运行 bun run sync-veltra-compositions 或 bun run sync-skills 可重新生成 generated/。

导入约定

import {
  useModel,
  usePop,
  useVirtualizer,
  useTransition,
  useFallbackProps,
  useFormFallbackProps,
  useFormComponent,
  useConfig,
  useComponentProps,
  useDrag,
  useFocus,
  useReactiveSize,
  useResizeObserver,
  useObserverCallback,
  useUserAction
} from '@veltra/compositions'

按需只引入用到的函数即可；无默认导出。

函数速查（14）

| 函数 | 用途 | 关键参数 / 行为 | 返回值要点 | | ------------------------------------------- | --------------------------------------- | --------------------------------------------- | --------------------------------------- | | useModel | 自定义 v-model（非 defineModel 场景） | propName、local（bool 或函数）、shallow | 类 ref 的 { value } | | useUserAction | 用户动作期间阻断 modelValue 回流副作用 | 无 | { userAction, isUserActive } | | useDrag | 拖拽（如对话框标题栏） | 目标 ref、边界等 | 拖拽状态与控制 | | useFocus | 焦点与 hover 语义 | 回调 | focus、handleFocus、handleBlur 等 | | useTransition | 过渡：css 或 style | target、name / style 关键帧 | enter、leave | | usePop | Popper 定位 | triggerRef、contentRef、direction | update、popperContainerId | | useReactiveSize | 响应式测量尺寸 | 元素 / 尺寸源 | 尺寸 ref | | useResizeObserver / useObserverCallback | ResizeObserver 与回调辅助 | 监听目标、选项 | 见 use-resize-observer 源码 | | useVirtualizer | 虚拟列表低阶适配层 | count、scrollEl、contentEl / beforeEl / afterEl、estimateSize | { virtualizer, snapshot, items, isScrolling }；尺寸走 DOM 命令式写入，业务语义由消费者组装 | | useFallbackProps | props → 全局 config 回退 | 源对象数组、默认值表 | 各字段 ref | | useFormFallbackProps | 表单场景三级回退 | [formProps, props] + 默认值 | 同上 | | useFormComponent | 表单 provide / inject | 父级传入 props；子级无参 | formProps、inForm 等 | | useConfig | 全局文档/尺寸等配置 | 读配置 | config 等 | | useComponentProps | 规范化组件 props | 视具体 API | 见源码 |

按场景选用

状态与并发

• useModel：需要非 modelValue 的 prop 名、或 local 函数在受控/非受控间切换（如表格 current 行）。
• useUserAction：用户动作期间阻断由 modelValue 回流引起的同步副作用；通过 userAction(fn) 包装事件处理函数（不要自调用），副作用侧用 isUserActive() 早返。

UI 交互

• useDrag、useFocus：对话框拖拽、输入框聚焦管理。
• useTransition：浮层、对话框内部需要程序触发 enter/leave 的过渡（常与 usePop 搭配）。

布局与列表

• usePop：下拉、Tooltip 等浮动层定位。
• useReactiveSize、useResizeObserver：随容器变化重算布局。
• useVirtualizer：大列表、下拉选项、表格体虚拟化的 Vue 胶水层；返回 { virtualizer, snapshot, items, isScrolling }，尺寸走 DOM 命令式写入（contentEl / beforeEl / afterEl），virtualEnabled / v-for :key / scrollTo 对齐模式等业务语义由消费者显式组装。

表单

• useFormComponent：在 UForm 与子控件间同步上下文。
• useFormFallbackProps：表单子组件上统一 size / disabled / readonly 等。
• useFallbackProps：脱离表单时的同一套回退逻辑。
• useConfig：读取全局尺寸等，与 @veltra/styles 的 loadTheme 协同。

组件增强

• useComponentProps：对传入 props 做归一化或兼容层（见源码中注释）。

延伸阅读（旧版参考文档）

与 generated/ 镜像互补：源码定位、模块地图与编写模式。

• references/source-discovery.md
• references/api-map.md
• references/patterns.md

维护

• 源码权威位置：packages/compositions/src/。
• 修改 API 后请运行 bun run sync-veltra-compositions 更新 generated/，以便技能文档与类型保持一致。