3
0
0

别再让 AI 手搓下拉框了:Vercel 开源 UI SDK 实测,键盘、焦点、ARIA 全部内置

2026-11-17
2026-11-17
文章摘要
|

AI 写 UI,总差最后一步

让 AI 写页面,速度早就不是问题——一句「帮我做个搜索框」,组件骨架十秒就出来了。但每次 review 到细节总会卡在同一批地方:弹层忘了 Esc 关闭、下拉列表没法用键盘导航、清空按钮一点焦点就丢了、屏幕阅读器读不出按钮状态。这最后 10% 的交互脏活,恰恰是 UI 工程里最难写、AI 最容易漏的部分。

Vercel 上月底在 GitHub 开源的 UI SDK(vercel-labs/ui)就是冲着这个问题去的:与其教 Agent 每次从头手搓,不如把「行为」本身做成库,让 Agent 只负责组装。README 里甚至直说了:「别担心,你不需要学会写这些。你的 Agent 会。而且我们把它们练得特别擅长。」我把这套库拉进沙盒实测了一圈,这篇文章把核心概念、实测结果和上手门槛一次讲清。

一、三周 5,000+ 星:给 Agent 用的「行为库」

先看基本面:2026 年 10 月 26 日开源,截至本文写作已有 5,285 星、172 个 fork,Apache-2.0 协议,TypeScript 编写。npm 端 11 月 12 日才发出第一个 beta,五天连发 6 版,最新 @ui-sdk/core 0.1.0-beta.6 是 11 月 16 日刚发的——迭代速度拉满。

它的定位是 headless 行为库:键盘导航、焦点、选择、消失、弹层、拖放,以及这些交互需要的全部 ARIA 属性,都做成可组装的积木。配五个框架适配器——React、Vue、Svelte、Solid 和 Web Components,同一份行为定义,五个框架渲染出同一个组件。现成组件也有 50 多个,从 Select、Dialog、Toast 到 Command、Tree、Image Cropper 都有。

和 Radix/shadcn 的区别一句话说清:Radix 是给人用的无头组件库,UI SDK 是给 Agent 用的行为库。它的文档分发、安装方式、API 设计,都是按「Agent 怎么消费」来优化的。

二、为 Agent 设计的三个证据

证据一:安装方式就是一段 prompt。官方 Quick Start 不是写给人看的教程,是让你直接粘给 Agent 的(React 版节选):

Set up ui-sdk in this React project. It needs React 19 or newer.

1. Install @ui-sdk/react and @ui-sdk/core with the project's package manager.
   If a release-age policy blocks the install, stop and ask me instead
   of changing it.
2. Add a note to AGENTS.md, creating it if needed: before using ui-sdk,
   follow the ui-sdk skill if it's installed, and read
   node_modules/@ui-sdk/react/docs/llms.txt.
3. If you support skills, run: npx skills@latest add vercel-labs/ui --skill ui-sdk

注意这些细节:装 beta 包被版本策略拦住时「停下来问我,别自己改策略」;让 Agent 在 AGENTS.md 里留备忘,防止下个会话的 Agent 忘记规矩。这些坑位显然是被真实的 Agent 踩出来的。

证据二:文档随 npm 包发布。装完包,node_modules/@ui-sdk/react/docs/llms.txt 就是文档索引——Agent 不用联网搜文档,读本地文件,版本天然对齐。skill 文件里甚至明确教 Agent:「core.md 超过 300 KB,按标题搜索,别整个读」——连 Agent 的上下文预算都替你算好了。

证据三:官方 skill 一行装进 Agent。

npx skills@latest add vercel-labs/ui --skill ui-sdk

不支持 skills 的 Agent 也不碍事,skill 文件就躺在 node_modules/@ui-sdk/core/skills/ui-sdk/SKILL.md,路径指过去就行。装完后对 Agent 说人话:

Use ui-sdk to build a five-star rating in React.
Arrow keys should move between stars and choose a rating.
Use our existing styles and test the keyboard behavior.

它会自己读文档、挑行为、定义 primitive、渲染成你框架的组件,最后自己把键盘行为测一遍。

三、核心概念:一个 primitive = 状态 + API + 槽位

UI SDK 里一切组件的起点是 definePrimitive。拿官方教程里的静音按钮举例,完整代码就这么长:

import { definePrimitive } from "@ui-sdk/core"

const muteButton = definePrimitive({
  name: "mute-button",
  state: () => ({ muted: false }),
  api: (context) => ({
    toggle: () => context.store.set({ muted: !context.store.get().muted }),
  }),
  slots: (slot) => ({
    root: slot({
      attrs: (state) => ({
        type: "button",
        "aria-pressed": String(state.muted),
      }),
      press: ({ api }) => api.toggle(),
    }),
  }),
})
  • state:内部状态,muted 初始 false;
  • api:改变状态的函数,这里只有 toggle;
  • slots:槽位描述——root 槽位渲成一个原生 button,aria-pressed 跟着状态走,press 时调 toggle。

关键在 attrs 那几行:无障碍属性不是你手写的,是状态驱动、自动同步到 DOM 的。这就是「行为库」和「每次现场手搓」的本质区别。

四、五框架同构渲染:Web Components 版连打包器都不要

primitive 本身不渲染任何东西,渲染靠各框架的适配器。React 里用 createParts:

import { createParts } from "@ui-sdk/react/primitive"
import { muteButton } from "@/lib/mute-button"

const { Root: MuteButton } = createParts(muteButton, { root: "button" })

// 使用:<MuteButton>Mute</MuteButton>

Vue、Svelte、Solid 的写法几乎一模一样,换个包名而已。Web Components 版本最省事,注册完直接写 HTML:

import { createParts, wrappedButton } from "@ui-sdk/web"
import { muteButton } from "@/lib/mute-button"

createParts(muteButton, {
  root: { tag: "mute-button", target: wrappedButton },
})

// HTML 里直接用:
// <mute-button><button>Mute</button></mute-button>

我在 Node 24 + jsdom 的沙盒里实跑了这个 Web Components 版本(core/web 均为 0.1.0-beta.6),注册、点击、状态翻转全部符合预期:

registered: true
初始 aria-pressed = "false",内层 button 自动挂上 data-slot="mute-button"
第一次点击 → aria-pressed = "true"
第二次点击 → aria-pressed = "false"

因为内核是原生 <button>,点击、Enter、Space 都会触发 press,屏幕阅读器从 aria-pressed 读状态——键盘和无障碍支持,一行代码没写就达标了。

样式完全留白,官方推荐用 data-slot 当钩子、状态属性当选择器,这份 CSS 五个框架通用:

[data-slot="mute-button"] {
  border: 1px solid #e5e5e5;
  border-radius: 0.5rem;
  padding: 0.375rem 0.75rem;

  &:focus-visible {
    outline: 2px solid #a3a3a3;
    outline-offset: 2px;
  }

  &[aria-pressed="true"] {
    background: #171717;
    color: white;
  }
}

五、行为组合实测:搜索框的「清空」按钮,三个脏活一次做完

行为库的真正价值在组合。官方 README 的 search-field 例子:清空按钮只在有内容时出现,点了清空,焦点要回到输入框而不是丢掉——这正是 AI 手搓最容易翻车的三件事。核心定义:

import { createFocusRecovery, definePrimitive } from "@ui-sdk/core"

const searchField = definePrimitive({
  name: "search-field",
  state: () => ({ value: "" }),
  api: (context) => ({
    set: (value) => context.store.set({ value }),
    recovery: createFocusRecovery({
      fallback: () => context.element("input"),
    }),
  }),
  slots: (slot) => ({
    input: slot({
      attrs: (state) => ({ value: state.value }),
      on: { input: (e, { api }) => api.set(e.target.value) },
    }),
    clear: slot({
      present: (state) => state.value !== "",
      attrs: () => ({ type: "button" }),
      press: ({ api }) => api.set(""),
      bind: (el, part) => part.api.recovery.bind(el, part),
    }),
  }),
})

三个细节:present 做条件渲染,实现是自动加/移除 hidden 属性;createFocusRecovery 是内置行为,fallback 指向 input——按钮从 DOM 消失的瞬间把焦点接住、送回输入框;bind 把这个行为绑到 clear 槽位上。

同样在 jsdom 里实测,三个行为全部命中:

初始:清空按钮带 hidden 属性,不可见
输入 "hello":hidden 自动移除,type="button" 自动注入
点 Clear:value 清空、hidden 回来,activeElement 自动落回 input

条件渲染、属性响应、焦点恢复——一个 hidden 属性都没手写,全是状态驱动的。

六、更激进的玩法:WebMCP,让浏览器里的 Agent 直接操作你的组件

UI SDK 还带了 registerTools,通过浏览器的 document.modelContext API 暴露三个工具:snapshot(读组件树)、query(查询)、act(执行操作)。如果浏览器内置了 Agent,它可以真的「看见」并操作你页面上的组件——按按钮、填表单:

import { registerTools } from "@ui-sdk/react/agent"
import { agent } from "./agent"

const unregister = registerTools(agent, {
  allow: (step) => step.action !== "press" || confirm(`Press ${step.args[0]}?`),
})

浏览器开发者工具里调试网页组件

安全设计也想过了:allow 回调对每一步把关,上面例子里每次 press 都会找人确认;act 工具带 consequentialHint 标记,浏览器可据此在执行前询问人类;还可以给危险控件加 data-agent-confirm 属性,强制人工拍板。浏览器不支持 modelContext 时这段代码静默无效,不用自己做特性检测。

七、上手前要知道的四件事

  • 还在 beta:受 Vercel beta terms 约束,GA 之前 API 可能变,生产项目建议先在边缘场景试水;
  • 版本门槛不低:React 19+、Vue 3.5+、Svelte 5.33+、Solid 2(@solidjs/web 要 2.0.0-rc.14+),老项目得先升框架;
  • 安装体积有感:@ui-sdk/core 装完约 7.9 MB——dist 全量组件目录占 6.9 MB,随包文档加 skill 约 1 MB;好在入口 index.js 只有 7 KB,按需 tree-shaking 后进包的代码很小;
  • 行为目录够深:focus、lists、popups、selection、trees、drag-and-drop、motion、canvas、direct-manipulation、preferences 十类行为,50 多个现成组件覆盖不了的场景自己拼积木。

写在最后

UI SDK 赌的判断很明确:未来越来越多的 UI 会是 Agent 写的,那组件库的 API、文档分发、安装方式就该围绕 Agent 重新设计一遍。三周 5,000+ 星,说明这个判断踩中了风口。

对我这种天天让 AI 写页面的人来说,收益很实际:焦点管理、键盘导航、ARIA 这些「永远差最后一步」的脏活有库兜底之后,AI 生成的 UI 终于能直接见人了。仓库在 github.com/vercel-labs/ui,文档在 ui-sdk.dev/docs,感兴趣的先把那段安装 prompt 丢给自己的 Agent 试试。

以上内容为 GLM 5.3 Agent 整合定时发布。

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

别再让 AI 手搓下拉框了:Vercel 开源 UI SDK 实测,键盘、焦点、ARIA 全部内置
/archives/tech-blog-2026-11-17
作者
番茄酱唉
发布于
2026-11-17
许可协议
CC BY-NC-SA 4.0

评论

欢迎来到我的博客!