外观

Primitives ​

Primitives 不是另一套 UI 组件清单，而是 Varo 的运行时契约：它们定义状态、触发器、遮罩、定位与关闭行为，让 H5 与小程序封装共享同一套交互语义。展示类组件继续留在组件文档；这里只保留会影响行为组合的底层能力。

01

运行时契约

Root 负责状态与上下文，Trigger 负责入口，Content/Overlay 负责可见层，Close 负责退出动作。平台可以换渲染细节，但不能改变契约。

02

组合顺序

先放 Root，再放 Trigger，然后放 Overlay 与 Content。组合顺序稳定后，业务 blocks 才能在 H5 和小程序间保持一致。

03

受控与非受控

简单场景使用内部状态；需要埋点、路由同步或表单联动时，切换到受控写法。

目录 ​

当前 17 个公开 primitives 按能力分组。每个页面都包含 H5 实时预览、小程序运行时契约、可复制代码与 API。

基础控件

2
Button打开文档

统一 pressed、disabled、loading 与原生激活语义。

Parts ButtonRoot / usePressableRoot
Input打开文档

文本值、格式化、只读、校验与输入事件基座。

Parts InputRoot / useFieldRoot

选择与切换

6
Number Field打开文档

数值边界、步进、精度与组合式加减控件。

Parts NumberFieldRoot / Decrement / Input / Increment
Checkbox打开文档

选中态、禁用态与 indicator 渲染契约。

Parts CheckboxRoot / CheckboxIndicator
Radio Group打开文档

单选组 value 与选项级 disabled 语义。

Parts RadioGroup / RadioItem / RadioIndicator
Switch打开文档

开关态、loading 与 disabled 契约。

Parts SwitchRoot / SwitchThumb
Tabs打开文档

当前 tab value、orientation 与 panel 关联。

Parts TabsRoot / TabsList / TabsTrigger / TabsContent
Select打开文档

选择器状态、open 契约与选项组合。

Parts SelectRoot / Trigger / Value / Content / Item

内容与布局

3
Image打开文档

图片加载、失败、占位与尺寸适配状态。

Parts ImageRoot / useImageRoot
Cell打开文档

列表行、设置项、链接行与键盘激活契约。

Parts CellGroupRoot / CellRoot
Sticky打开文档

吸顶状态、偏移量与滚动事件适配。

Parts StickyRoot

展开与轻浮层

3
Collapsible打开文档

单个展开区域的 open 状态契约。

Parts CollapsibleRoot / Trigger / Content
Accordion打开文档

single/multiple 展开集合与 item disabled。

Parts AccordionRoot / Item / Trigger / Content
Popover打开文档

轻量浮层开关与显式 dismiss 契约。

Parts PopoverRoot / Trigger / Content / Close

遮罩与弹层

3
Dialog打开文档

模态打开态、遮罩、内容与退出动作。

Parts DialogRoot / Trigger / Overlay / Content / Close
Overlay打开文档

遮罩可见态、点击关闭与滚动锁定。

Parts OverlayRoot
Popup打开文档

带定位、遮罩、安全区与关闭行为的弹出层。

Parts PopupRoot

下一批基础候选 ​

基础能力不是越多越好：只有当状态、键盘/触摸行为或 dismiss 逻辑会被多个组件重复使用时，才下沉为 primitive。

候选可支撑的上层组件下沉价值
TooltipTooltip、图表提示、截断说明延迟打开、悬停/聚焦与关闭策略
Menu / DropdownMenu下拉菜单、右键菜单、操作菜单roving focus、方向键与选项激活
ToggleGroup分段控制、格式工具栏、筛选器单选/多选集合与 roving focus
Slider音量、范围、参数调节边界、步进、键盘和拖动状态
Combobox / Listbox搜索选择、远程选择、命令面板输入、过滤、active option 与选择状态
Toast全局反馈、异步结果、撤销提示队列、生命周期、暂停与关闭

优先级应是 Menu、Tooltip、ToggleGroup、Slider，再评估 Combobox 与 Toast；它们的跨端输入模型更复杂，需要先锁定 H5 与小程序行为边界。

产品边界 ​

  • primitive 管行为契约：受控/非受控状态、disabled、ARIA、data-* 与 dismiss 事件。
  • UI wrapper 管视觉与定位：token、动画、图标、浮层位置与平台渲染细节。
  • 业务 wrapper 管数据与场景：远程搜索、权限、分页、领域模型与业务文案。

这个分层让 Base Kit 源码保持可读可改；团队可以基于相同 primitives 创建自己的 UI 包和业务组件，而不需要复制状态机。

开发约定 ​

  • H5 与小程序使用同一套 part 名称与状态模型。
  • 同一 TabsRoot / AccordionRoot 内的 value 必须唯一。
  • 小程序页不把浏览器渲染伪装成真实小程序预览；文档用「运行时契约」说明差异。
  • 自定义业务 UI 请从 primitives 向上封装，或参考 组件文档 与后续 Blocks 作者指南。

相关文档 ​