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/ 镜像互补：源码定位、模块地图与编写模式。
维护
- 源码权威位置：
packages/compositions/src/。 - 修改 API 后请运行
bun run sync-veltra-compositions更新generated/，以便技能文档与类型保持一致。