Headless UI组件库设计封装：中央厨房里的逻辑与视觉分离之道

可视化演示

展示Headless UI模式的逻辑视图分离架构、Props契约设计与WAI-ARIA无障碍支持，切换模式查看核心设计原则。

设计理念

云膳集团把“后厨与门店分离”这个决定，经历了三个阶段。最早是夫妻店：一个大厨从前台收银到后厨颠锅全包，对应早期前端把 HTML、CSS、JS 混在一起写。接着是连锁时代：总部连装修带菜谱统一供给，门店省心但千篇一律，这对应 Bootstrap、Ant Design 这类样式组件库——上手快，想改品牌风格却很难。最后才是中央厨房时代：总部只产出标准化的半成品包，门店自主摆盘，这就是 Headless UI。

技术上的“半成品包”就是组件的逻辑内核：状态的开关、键盘的响应、读屏器的语义标注。它不包含任何颜色、圆角、间距等长相信息，也不直接产出视觉 DOM。消费方拿到这份半成品包后，自己决定渲染成什么样子，这就叫“无头”——有大脑，没有五官。

这样设计有三个直接收益：第一，逻辑可跨框架复用，同一套行为在 React、Vue、Svelte 里都能用；第二，复杂交互与无障碍在源头就保证，不用每个项目重写；第三，视觉完全自由，设计系统、主题换肤都变成门店摆盘的事。不过它也有边界：如果只是搭一个静态营销页，用 Headless 就像为炒一盘蛋炒饭建一座中央厨房，属于过度设计。

回到云膳：这套公式说明，“云顶”可以在半成品包上摆法餐的盘，“一碗香”浇上自己的辣油，“云夜”撒一把葱花取暖。菜还是那道菜，端上桌却各有各的活法——这就是逻辑与视觉分离的底层哲学。

核心原理

中央厨房的秘诀在“流程卡”。一份红烧牛肉从选料到出锅，每一步都有标准作业流程：切块尺寸、焯水时间、收汁火候。门店不需要知道细节，拿到半成品包就能出菜。Headless 逻辑内核也一样，把“状态怎么流转、行为怎么触发”固化成流程卡，就构成了它的三个核心原理。

第一是状态上提。所有交互状态（对话框是否展开、菜单高亮到哪一项）都集中在逻辑层统一管理，而不是散落在消费方的各个组件里。逻辑层内部用“旧状态 + 动作 → 新状态”的方式流转，像中央厨房的流程卡一样每一步都有据可查。

第二是行为封装。键盘事件、点击外部关闭、Escape 退出这类常用行为被预先编排好，作为“行为包”随半成品包交付。第三是渲染代理——逻辑层不亲自下厨，它把“最终长什么样”的裁决权完全代理给调用方：调用方要按钮就渲染按钮，要链接就渲染链接。三个原理合起来，就是“状态归我管、行为我打包、长相你决定”，门店因此获得了最大的创作自由。

实现模式

中央厨房向门店开放三种合作方式：素料包、委托代工、组合套餐。对应到 Headless 组件，就是三种主流实现模式，设计组件库时按场景选用。

第一种是自定义 Hook（素料包）。逻辑层写一个 Hook，如 useDialog()，返回状态、行为函数和一组“接线属性”。消费方像门店拆开素料包一样，自行决定把属性绑到哪些元素上。这种模式自由度最高，适合团队已有成熟设计系统、只需要补行为的情况。

第二种是 Render Props（委托代工）：组件接收一个 render 函数，把状态和行为作为参数交回去，由调用方决定这段区间渲染成什么。第三种是组合组件（组合套餐）：Dialog.Root 负责状态，Dialog.Trigger 负责触发，Dialog.Content 负责面板，通过 Context 共享同一份逻辑，门店不必手动传参，抄起套餐就能开火。三种模式没有绝对优劣，实际组件库常常混用：复杂控件用组合组件，简单行为用自定义 Hook。

无障碍交互

门店可以随意摆盘，但有一条红线谁都不能碰：食品安全标准。云膳的中央厨房要求所有半成品包必须通过统一质检，对应到 Headless 组件，就是无障碍（Accessibility）绝不允许被视觉层“改良”掉。逻辑层必须内置对屏幕阅读器、键盘用户的完整支持，这是设计底线。

首先是 ARIA 标准。逻辑层自动给关键元素注入语义标注，告诉读屏软件“这是个对话框”、“现在处于展开状态”。视力正常的用户看到的是漂亮面板，盲人用户“听到”的则是清晰的结构。

其次是键盘导航：方向键移动高亮、Tab 进入/跳出、Escape 关闭、Home/End 跳转首尾，全部由逻辑层接管；最后是焦点管理：打开对话框时焦点移入面板并锁死（焦点陷阱），关闭时焦点归还给触发按钮（焦点恢复）。这些行为表面看不见，却是“食品安全”级别的硬指标——任何门店的摆盘都不能破坏它。

生态对比

市面上有几家成熟的“中央厨房”供货商，选谁相当于决定半成品包的标准化程度。云膳选供应商时会看三件事：配不配合自有门店体系、食品安全认证全不全、供货稳不稳。前端选 headless 库同理。

Radix UI：面向 React 生态的原语组件库，切到最细粒度，几乎不预设任何样式，适合用它搭建自有设计系统，如同给高端私厨定制的顶级食材包。Headless UI（Tailwind 出品）：同时支持 React 与 Vue，与 Tailwind CSS 天然默契，主打“开箱即上菜”，适合快速交付的团队。React Aria：Adobe 开源，无障碍覆盖面最广，交互行为最严谨，适合对合规性要求极高的企业级产品。

选型没有标准答案，只有“匹配度”。就像云顶选顶级食材包、一碗香选快速半成品、云夜选全合规供应——把自家门店的定位想清楚，供货商的答案自然浮现。

工程化实践

中央厨房要按年度接受品控审查，靠的是一本品控手册：原料台账、出餐抽检、操作记录。Headless 组件库的工程化落地，同样需要三份“手册”：类型设计、测试策略、文档建设。

第一份手册是类型设计。用 TypeScript 泛型把组件 API 提炼成可推导的类型契约：用户传入一个选项数组，onSelect 的回调参数就能自动推导出对应类型。类型即文档，编译期就能拦截大部分误用，相当于品控手册在原料入库时就完成初检。

第二份手册是测试策略：逻辑层跑行为单测（打开、关闭、高亮移动），渲染层跑快照，再用 Playwright 模拟真实键盘路径做端到端测试，确保任何门店摆盘都不破坏键盘流程。第三份手册是文档建设：每个组件配备可交互范例（Storybook）、行为说明和键盘操作表。三份手册齐了，这座中央厨房才敢对外大规模供货。

封装策略

中央厨房把半成品包交给门店后，门店要写一本“摆盘手册”:怎么装饰、怎么配色、怎么贴品牌标识。在 Headless 组件库的消费端，这份手册就是封装策略——把无头逻辑包装成自家有头组件。

最直接的封装是样式注入：无头组件提供 className 入口，消费方注入自己的样式类；多个来源的类名要按规则合并，不能互相覆盖。这就像半成品包上的“建议摆盘”标签：允许门店替换、增删、组合。

第二招是语义化插槽（如 Radix 的 asChild 模式）：允许“把行为穿到任意标签上”，让 div、a、button 都能继承触发逻辑，彻底打破标签限制。第三招是主题定制：用 CSS 变量（设计令牌）定义颜色、间距、圆角，门店只需改一套变量值就能完成全店换肤。三招配合，门店既能保住自家风格，又不破坏中央厨房的标准化内核。

AI 应用场景

Python 演示

"""无头列表选择器：逻辑内核与视觉皮肤彻底分离的演示"""class HeadlessListbox:    """逻辑内核：只管理状态与行为，不关心任何样式"""     def __init__(self, options):        self.options = options        self.highlight = 0        self.expanded = False     def dispatch(self, action):        """Reducer：中央厨房的标准操作流程"""        if action == 'toggle':            self.expanded = not self.expanded        elif action == 'next' and self.expanded:            self.highlight = (self.highlight + 1) % len(self.options)        elif action == 'prev' and self.expanded:            self.highlight = (self.highlight - 1) % len(self.options)        elif action == 'close':            self.expanded = False        return self.get_state()     def get_state(self):        """半成品包：只暴露消费者需要的状态"""        return {            'expanded': self.expanded,            'active': self.options[self.highlight],            'total': len(self.options),        }  def render_plain(state):    """门店A：极简纯文字摆盘"""    mark = 'v' if state['expanded'] else '>'    return f" {state['active']} {mark} (共{state['total']}项)"  def render_fancy(state):    """门店B：带装饰符号的活泼摆盘"""    head = f"* {state['active']} *" if state['expanded'] else f"  {state['active']}  "    return head + (' [展开中]' if state['expanded'] else ' [已收起]')  def main():    box = HeadlessListbox(['红烧牛肉', '卤蛋', '时蔬', '例汤'])    print('=== 同一逻辑内核，两种摆盘 ===')    print('默认  :', render_plain(box.get_state()))    box.dispatch('toggle')    for _ in range(3):        box.dispatch('next')    print('门店A :', render_plain(box.get_state()))    print('门店B :', render_fancy(box.get_state()))    box.dispatch('close')    print('收起  :', render_plain(box.get_state()))  if __name__ == '__main__':    main()

1. class HeadlessListbox逻辑内核类，对应中央厨房：不包含任何样式信息。
2. dispatch(self, action)Reducer 入口，状态流转都从这里走，action 只传意图不传结果。
3. self.expanded = not self.expanded切开关闭状态的纯逻辑操作，不带任何 UI 依赖。
4. get_state()返回“半成品包”，消费者只拿到这一个入口，内部细节完全隐藏。
5. render_plain(state)` / `render_fancy(state)两家门店的摆盘函数，接收同一份 state 却输出完全不同风格。
6. box.dispatch('toggle')模拟用户点击触发，逻辑层响应后状态更新，门店随之重摆。

常见误区

面试题