Vibe Coding 术语大全
Vibe Coding 生态的核心术语、工作流模式、工具链和最佳实践的系统整理。从 Karpathy 的定义出发，覆盖 AI 编程时代的每一个关键概念。
一、什么是 Vibe Coding
二、核心概念
1. 前端（Frontend）
用户在网页、小程序和软件里直接看到、点击和输入的那一层。
例如，在注册页，输入框、提交按钮和"正在提交 / 注册成功 / 出错了"的提示属于前端；账号是否真正创建成功，要由后端处理后返回结果。
关键边界：前端代码会交给浏览器运行，访问者可以查看或修改；密钥、价格和权限规则不能只放在前端。
一次保存的完整链路：前端（浏览器）→ API（约定）→ 后端 → 数据库
常见问题
老听人说前端、后端，这两个到底有什么区别？
诊断题
页面提示保存成功，刷新后却恢复原样。先检查什么？
A. 对照保存请求、成功提示出现时机，以及刷新后的读取响应 B. 先清除浏览器缓存并刷新，观察旧值是否还会出现 C. 把成功提示延迟一秒，再重复保存和刷新
如何告诉 AI Agent
页面点保存以后会提示成功，但一刷新内容就没了。先检查前端是不是提前显示成功，以及它有没有正确处理保存请求和刷新后的读取结果。找到问题再改，改完重新保存并刷新确认。
2. HTML
HTML 是用标签描述网页内容结构、供浏览器渲染页面的标记语言。
它用标签标出标题、段落、图片、链接和按钮。产品页面的内容层级由 HTML 组织；视觉样式通常交给 CSS，复杂交互需要 JavaScript。
别名：HTML 页面结构 · 超文本标记语言
基本结构
<html>
<head> → 元信息
<body>
<h1> → 标题
<p> → 段落
<a> → 链接
</body>
</html>
常见问题
AI 写出来的代码里一堆
< >和英文单词，这些东西是干嘛的？
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 把标题、图片和章节组织成清楚的网页结构 | 标签忘记关闭，后续结构被破坏 |
| 制作可直接分享的页面：官网、落地页、图文文章 | 标签交叉嵌套，浏览器难以得到预期结构 |
| 加入图片、链接和交互元素 | 正文内容误放在 <head> 里 |
| 把 Markdown 转成需要正式呈现的网页 | 用 Word 另存为 HTML，破坏标签结构 |
Anatomy：四个组成部分
| 部分 | 说明 |
|---|---|
| 开始标签 Opening Tag | 尖括号加标签名，告诉浏览器「这里开始」 |
| 属性 Attribute | 写在开始标签里的附加信息，如链接地址、图片路径 |
| 内容 Content | 两个尖括号之间的部分，改文案只动这里 |
| 结束标签 Closing Tag | 多一个斜杠，告诉浏览器「到这里结束」 |
常见标签速认
| 标签 | 用途 |
|---|---|
<div> | 通用容器，组织内容和布局 |
<h1> ~ <h3> + <p> | 标题和段落，文章的骨架 |
<a> + <img> | 链接跳转 + 图片 |
<button> + <input> | 页面上能点能填的交互件 |
典型场景：AI 给你的 index.html
帮我做一个个人主页
<h1>小狸的主页</h1> <p>我喜欢爬山和拍照。</p> <a href="/photos">看我的相册</a>
3. 组件（Component）
组件是把一块可复用的界面和它负责的行为组织在一起的单元。
例如商品卡在首页、搜索结果和收藏页都显示图片、价格和购买按钮时，可以共用同一个组件；表单输入框也能作为组件复用。它划分的是界面责任，不等于页面里每一个小标签都必须单独成为组件。
别名：UI 组件 · 界面组件 · UI Component
前置知识：HTML
核心逻辑：同一种卡片在不同页面共用
发现重复 → 抽成组件 → 改一处同步
首页 搜索结果
┌──────────┐ ┌──────────┐
│ 商品卡 │ │ 商品卡 │ ← 同一个组件，传入不同数据
│ 图片 价格 │ │ 图片 价格 │
│ 购买按钮 │ │ 购买按钮 │
└──────────┘ └──────────┘
组件负责什么
- 把重复责任放在一起：卡片的结构、样式和点击后的行为可以一起维护
- 价格格式或按钮文案改变时，不必在三个页面分别修改
- 组合后才成为完整页面：导航、商品卡、筛选区等组件由页面按场景排列
- 同一组件可接收不同商品数据，却保持一致的交互和外观
容易混淆的地方
- 组件不是框架专属概念——React、Vue 或原生网页都可以有组件
- 组件 ≠ 整张页面
- 只有一次出现、没有独立责任的简单文字，不必为了复用而强行拆分
常见问题
把这个重复出现的商品区做成组件，改一个地方就能同步更新。
诊断题
活动页、首页和搜索页都要显示相同规则的"活动卡"。哪种做法最便于后续统一修改？
A. 把图片、标题、状态和点击行为放进一个活动卡组件，让三个页面传入各自的数据 B. 在每个页面复制一份卡片代码，之后分别改标题和按钮 C. 把所有页面和所有功能塞进一个叫"网站"的组件
如何告诉 AI Agent
请把重复出现的活动卡整理成组件。首页、活动页和搜索结果都使用它，但保留各自传入的图片、标题和状态。改完后检查三个页面的卡片外观和点击行为一致。
来源：VibeHub · 组件
4. 状态（State）
状态是界面在当前时刻需要记住、并会随操作或结果变化的信息。
例如表单正在提交、弹窗是否打开、购物车数量和当前筛选条件都是状态；同一个组件会根据这些值显示不同画面。它不是组件本身，也不是所有长期数据都应只放在页面状态里。
别名：UI 状态 · 界面状态 · UI State
前置知识：组件
一次保存的四种状态
默认 → 保存中 → 成功 / 失败
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ 昵称 │ │ 保存中… │ │ ✓ 已保存│ │ ✗ 失败 │
│ [保存] │ → │ [··] │ → │ │ → │ 重试 │
└────────┘ └────────┘ └────────┘ └────────┘
尚未提交 点击后 成功 失败
开始保存
状态怎样改变画面
- 记录当前而非永远：用户点击保存后，页面记住"正在提交"，以避免重复点击并显示等待；请求结束后再改为成功或错误
- 状态驱动画面：同一按钮和提示区会根据当前值显示不同内容。状态变化应来自真实操作或请求结果，不能只靠把成功文案提前写上去
容易混淆的地方
- 状态 ≠ 组件：组件是界面责任的边界，状态是组件内部记忆的数据
- 状态 ≠ 数据库：数据库保存跨设备、跨用户需要长期保留的数据；页面刷新后丢失的临时状态，不能证明服务端已经保存成功
常见问题
提交按钮点下去先显示保存中，成功或失败后再更新提示。
诊断题
用户点击保存后，页面马上显示"已保存"，但网络请求随后失败。哪个修改最合适？
A. 先进入"保存中"，只在请求成功后显示"已保存"，失败时显示可重试的错误 B. 保留立即显示"已保存"，因为用户不喜欢等待 C. 删除所有状态提示，避免出现错误文案
如何告诉 AI Agent
请检查这个保存流程的状态：点击后按钮显示"保存中"并禁用重复提交；只有接口成功才显示"已保存"，失败时显示错误和重试入口。改完后分别验证成功和失败两种结果。
来源：VibeHub · 状态
5. 按钮（Button）
按钮是让用户在当前页面执行保存、提交、删除等操作的可点击控件。
用户提交注册表单或保存设置时会点击按钮。链接负责前往别处；同一操作区应突出一个主要动作，其余动作降低层级。
别名：操作按钮
按钮 vs 分段控件
| 按钮 Button | 分段控件 Segmented |
|---|---|
| 点一下就执行一个动作 | 表示一组选项中当前选中了哪一个 |
| 用于提交、保存、删除 | 用于切换视图或模式 |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 按钮本体 Button | 整块可点击区域，有主要/次要/危险等类型 |
| 图标 Icon | 可选，强化动作含义；纯图标按钮要提供读屏名称 |
| 文案 Label | 动词开头，说清点完会发生什么 |
五种变体
| 变体 | 用途 | 示例 |
|---|---|---|
| 主要按钮 Primary | 同一操作区最重要的动作 | 保存 |
| 次要按钮 Outline | 取消、返回等退一步的操作 | 取消 |
| 文字按钮 Text | 最轻量的操作，如展开详情 | 查看详情 |
| 危险按钮 Danger | 删除、清空等不可挽回的操作 | 删除 |
| 加载与禁用 Loading & Disabled | 提交中或条件未满足时，防止重复点击 | 提交中… |
常见问题
帮我加个按钮，点了就能把内容存下来。
诊断题
账号设置页有保存资料、放弃本次修改、删除账号和前往重设密码。怎样安排更合适？
A. 保存、放弃修改和删除账号使用按钮；重设密码继续用链接，删除前确认 B. 把保存、放弃修改、删除和重设密码都做成跳转链接 C. 用一个"确认"按钮处理所有操作，点击后再猜用户想做什么
如何告诉 AI Agent
请整理账号设置页：保存资料、放弃本次修改和删除账号使用各自明确的按钮，删除前确认；"重设密码"保留为链接。不要改布局。分别触发保存、放弃修改和删除确认，确认保存中不能重复提交。
来源：VibeHub · 按钮
6. 链接（Link）
链接是带用户前往另一个页面、页内位置或资源地址的可点击文本或元素。
例如"查看订单详情"可打开详情页，"下载发票"可取得文件。链接不应用来提交或保存数据；这类动作应使用按钮。
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 页面之间跳转：去详情页、去设置页 | 需要执行操作（提交、删除、保存）→ 用按钮 |
| 正文里引用资料：协议、文档，不打断阅读节奏 | 整段文字都做成链接，点击范围过大 |
| 次级入口：列表末尾的"查看详情 →" | 文案只写"点击这里"，不说点了去哪 |
| 跳到外部网站：加 ↗ 告诉别人会离开本站 | 做成和普通文字一样，用户难以辨认可点击 |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 链接本体 Link | 整段可点击区域，通过文字样式、悬停和焦点状态让人看得出可以打开 |
| 链接文字 Anchor Text | 说清楚点了去哪，别写"点击这里" |
| 外部图标 External Icon | 可选，↗ 表示会离开本站 |
四种变体
| 变体 | 用途 | 示例 |
|---|---|---|
| 内联链接 Inline | 正文中间跳资料，不打断阅读 | 详情见帮助文档 |
| 独立链接 Standalone | 单独一行做次级入口 | 查看全部动态 → |
| 外部链接 External | 会跳到站外时用它，记得带 ↗ | 官方文档 ↗ |
| 弱链接 Subtle | 收起、换一批等不重要的跳转 | 收起评论 |
常见问题
这段文字要能让人点，点了跳到另一个页面。
诊断题
登录页底部有"还没有账号？立即注册"。这应该用链接还是按钮？
A. 用链接，因为它是导航到另一个页面（注册页），不是执行登录操作 B. 用按钮，因为它在表单附近 C. 用和"登录"一样的按钮样式，强调它的重要性
如何告诉 AI Agent
请检查这个页面：所有导航到其他页面的入口用链接，执行提交/保存/删除操作用按钮。外部链接加上 ↗ 标识，链接文字说清楚点了去哪，不要出现"点击这里"。
来源：VibeHub · 链接
7. 输入框（Input）
输入框是让用户填写账号、搜索词等短文本的表单控件。
账号、昵称和搜索词通常放在输入框中。字段名称要始终可见，格式错误要在附近说明；需要输入多行说明时应使用多行文本域。
别名：文本输入框 · 单行输入框
输入框 vs 相似控件
| 控件 | 区别 |
|---|---|
| 搜索输入框 | 输入框 + 提交/清除/搜索建议，用途更明确 |
| 自动完成 AutoComplete | 输入框只接收文字，AutoComplete 根据已输入内容给出可选建议 |
| 多行文本域 Textarea | 多行连续内容用 Textarea，短文本用 Input |
| 选择器 Select | 固定选项中选一个用 Select，自由填写用 Input |
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 登录、注册：账号密码等短文本 | 需要填写多行连续内容 → 用 Textarea |
| 搜索：输入简短关键词 | 必须从固定选项中选择 → 用 Select |
| 表单收集：姓名、邮箱逐行填 | 用 placeholder 替代 label，输入后字段用途不再可见 |
| 起名字、改标题：精确的短文本编辑 | 用输入框展示只读内容，让用户误以为可以修改 |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 标签 Label | 说明这里需要填写什么，始终可见 |
| 输入框本体 Input | 聚焦时高亮描边，错误时变红 |
| 辅助说明 Help Text | 补充格式要求或错误原因 |
五种变体
| 变体 | 用途 |
|---|---|
| 默认 Default | 绝大多数一行文本输入的通用形态 |
| 密码 Password | 密码、密钥等需要遮挡的内容 |
| 带前缀图标 With Icon | 搜索等场景，用图标暗示要填什么 |
| 错误状态 Error | 校验不通过时，红框配上出错原因 |
| 禁用 Disabled | 这一项暂时不允许用户修改 |
常见问题
页面上要有个填邮箱的地方。
诊断题
注册表单的"昵称"输入框，placeholder 写了"输入你的昵称"，但没有 label 标签。有什么问题？
A. 输入后 placeholder 消失，用户看不到这个字段要填什么了 B. placeholder 就是 label，不需要额外标签 C. 昵称不用 label，大家都看得懂
如何告诉 AI Agent
请检查所有输入框：每个输入框都有始终可见的 label，错误时在输入框附近显示具体原因而不是只变红，placeholder 只给示例不替代 label。密码框默认遮挡内容。
8. 多行文本域（Textarea）
多行文本域是让用户输入或编辑多段自由文本的表单控件。
评论、个人简介和给 AI 的提示词适合使用它，并可显示字数限制。只需要填写昵称等短内容时，普通输入框更直接。
前置知识：输入框
Textarea vs Input：什么时候用哪个
| 场景 | 用 |
|---|---|
| 发表评论、写回复：内容长短不限 | Textarea |
| 个人简介、项目描述：几句话说清一件事 | Textarea |
| 给 AI 写提示词：指令往往又长又具体 | Textarea |
| 有字数上限时配上实时计数 | Textarea |
| 只需填写单行内容（昵称、邮箱、标题） | Input |
| 需要从固定选项中选择 | Select |
| 需要加粗、插图或排版 | 富文本编辑器 |
| 展示只读内容 | 正文或描述组件 |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 标签 Label | 告诉用户写哪方面的内容 |
| 文本域本体 Textarea | 提供适合内容的初始高度，是否允许调整按场景决定 |
| 字数统计 Word Count | 接近上限时变红提醒 |
四种变体
| 变体 | 用途 |
|---|---|
| 默认 Default | 评论、反馈等常规多行输入 |
| 带字数统计 With Count | 有字数上限时，显示实时计数 |
| 只读 Readonly | 内容已确定，只展示不让改 |
| 禁用 Disabled | 整个文本域暂时不可编辑 |
常见问题
要让用户写一大段话，一行肯定不够。
诊断题
用户反馈说个人简介框太小，写了两行就看不到前面写了什么。怎么改进？
A. 给 Textarea 一个合理的初始高度（如 4-6 行），并允许用户手动拖拽调整 B. 缩小字体让更多内容可见 C. 把 Textarea 换成 Input，用户打字快一点就行
如何告诉 AI Agent
请把这段说明、回复或简介的输入区改成多行文本域，给个合适的初始高度，有字数限制时配上实时计数，用完提醒。不要把单行昵称、邮箱改成多行。
9. 数字输入框（InputNumber）
数字输入框是用于填写数值并按设定步长增减的表单控件。
购买数量、库存和价格可在这里直接输入或点加减号调整。它只能限制格式和范围，库存是否足够等业务规则仍要在提交时校验。
别名：Number Input · 数字步进器 · Numeric Stepper
前置知识：输入框
InputNumber vs 易混淆控件
| 控件 | 区别 |
|---|---|
| 步骤条 Steps | InputNumber 用来增减数值；Steps 展示流程包含几个阶段 |
| 滑块 Slider | 需近似选择数值时用 Slider，需精确数值用 InputNumber |
| 日期选择器 DatePicker | 日期有专门选择器，不用数字输入框凑 |
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 购物车改数量：点加减比敲键盘快 | 手机号、身份证号 → Input（数字字符串不能加减） |
| 设置库存、限购：整数且有业务含义 | 只需近似选择数值 → Slider |
| 有明确上下限：超出范围自动拦下 | 需要选择日期 → DatePicker |
| 价格、金额：需要固定小数位 | 数值范围很大时支持直接键盘输入，不只依赖加减按钮 |
Anatomy：四个组成部分
| 部分 | 说明 |
|---|---|
| 减少按钮 Minus | 点一下减一个步长 |
| 数值输入框 Input | 也可以直接键盘输入 |
| 增加按钮 Plus | 到上限后置灰 |
| 整体控件 | 输入框和加减按钮组成一个控件 |
四种变体
| 变体 | 用途 |
|---|---|
| 默认 Default | 数量、库存等常规纯数字输入 |
| 带单位 With Unit | 价格、件数等需要标清计量单位 |
| 小尺寸 Small | 卡片、行内等空间紧张的地方 |
| 禁用 Disabled | 这个数值当前不允许改动 |
常见问题
数量那里只能填数字，最好能直接按加减。
诊断题
购物车数量输入框允许用户输入负数或超过库存的值。怎么改？
A. 设置 min/max 上下限，超出范围自动拦下，库存校验在提交时后端再做一次 B. 让用户随便填，提交时再报错 C. 移除加减按钮，只保留键盘输入
如何告诉 AI Agent
请给数字输入框设置合理的 min/max 和步长，超出范围时自动拦下并给出提示。配上合适的单位。手机号这类数字字符串不要用数字输入框。
10. 单选框（Radio）
单选框是一组只能选中其中一个选项的表单控件。
选择支付方式或可见范围时，可将少量互斥选项直接列出。每组要有清楚的问题说明；选项较多或需要搜索时应改用选择器 Select。
Radio vs 易混淆控件
| 控件 | 区别 |
|---|---|
| 选择器 Select | 选项多、难以直接比较 → Select；少量互斥选项平铺 → Radio |
| 复选框 Checkbox | 多选用 Checkbox，单选用 Radio；只有一个"同意协议"也用 Checkbox |
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 少量互斥选项，直接平铺便于比较 | 选项多且难以直接比较 → Select |
| 隐私、可见范围这类关键设置 | 只有一个"同意协议"确认项 → Checkbox |
| 选项需要附带说明（费用、时效） | 允许多选 → Checkbox |
| 支付方式：经典的单选场景 | 需要取消选择时，增加"无"选项或改用 Checkbox |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 单选项 Radio | 整行都能点，不只是圆点 |
| 圆点 Dot | 选中后实心，同组互斥 |
| 选项文案 Label | 说清楚选了意味着什么 |
四种变体
| 变体 | 用途 | 示例 |
|---|---|---|
| 默认 Default | 互斥选项不多时的标准形态 | 支付宝 / 微信 |
| 按钮样式 Button | 选项少而短，想要更醒目好点 | 按月付 / 按年付 |
| 带说明 With Desc | 选项要附带费用、时效等解释 | 标准配送 免费·3天 |
| 禁用 Disabled | 某选项当前不可选但仍需展示 | 不可选（置灰） |
常见问题
这几个选项只能选一个，选了新的要把旧的取消掉。
诊断题
性别选择用了一个下拉框，里面只有"男""女""保密"三个选项。怎么改进？
A. 改成三个 Radio 直接平铺，点一下就能选，不用多一次点击展开 B. 在下拉框里增加更多性别选项 C. 改成三个按钮，点了直接提交
如何告诉 AI Agent
请检查这个单选组：选项不超过 5 个时改用 Radio 直接平铺，每组配上清楚的问题说明。选项附带费用/时效等解释时用带说明的样式。不要用 Radio 做多选。
11. 复选框（Checkbox）
复选框是让用户独立选中一个或多个选项的表单控件。
兴趣标签、筛选条件和同意协议都可使用复选框。每个选项彼此独立；只能选择一个答案时应使用单选框 Radio。
Checkbox vs 易混淆控件
| 控件 | 用 Checkbox | 不用 Checkbox |
|---|---|---|
| 单选框 Radio | 多选，选项独立 | 选项互斥只能选一个 |
| 开关 Switch | 需要点提交才生效 | 切换后立即生效的设置 |
| 按钮 Button | 勾选表示意愿 | 触发提交、删除等操作 |
| 多选 Select | 少量选项平铺 | 大量选项不宜全部平铺 |
什么时候用
| 场景 | 示例 |
|---|---|
| 多条件筛选：几个条件自由组合 | 进行中 / 已完成 / 已归档 |
| 兴趣、技能等多选收集 | 设计 / 前端 / AI / 数据分析 |
| 全选、批量操作：一键选中整组 | 全选 → 移动 / 删除 |
| 单独确认一件事 | 我已阅读并同意《用户协议》 |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 复选项 Checkbox | 整行都能点，互相独立 |
| 方框 Box | 勾选打对勾，部分选中显示横杠（半选态） |
| 文案 Label | 说清勾选后会怎样 |
三种变体
| 变体 | 用途 |
|---|---|
| 默认 Default | 多选或单独确认一件事时 |
| 半选 Indeterminate | 批量选择时，只勾了一部分（如全选框中部分子项已选） |
| 禁用 Disabled | 该选项当前不可勾选 |
常见问题
这几个选项不冲突，用户想选几个都行。
诊断题
"同意协议"用了一个 Radio，但用户选了就无法取消，只能刷新页面。怎么改？
A. 改成单个 Checkbox，用户点了可以再点取消勾选 B. 增加第二个 Radio "不同意" C. 不做任何修改，协议必须同意
如何告诉 AI Agent
请检查：多选场景用 Checkbox，每个选项互相独立；全选时用半选态表示部分选中。只有一个确认项（如同意协议）用单个 Checkbox 而不是 Radio。不要用 Checkbox 触发页面跳转或提交。
12. 开关（Switch）
开关是表示并立即切换一项功能开启或关闭状态的表单控件。
深色模式或自动保存适合用开关，并应在切换后反馈成功或失败。若多个设置需要统一保存，应改用复选框 Checkbox 配合按钮。
Switch vs 易混淆控件
| 控件 | 用 Switch | 不用 Switch |
|---|---|---|
| 复选框 Checkbox | 拨完立即生效 | 提交后才生效的偏好（需配合按钮） |
| 单选框 Radio | 开/关两种状态 | 三个以上互斥状态 |
| 按钮 Button | 即时切换状态 | 危险操作（删除数据等）需确认 |
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 设置页里的开/关项 | 提交后才生效的偏好 → Checkbox + Button |
| 拨完立即生效，最好给个反馈 | 危险操作（如删除全部数据）→ 需确认 |
| 功能列表逐个启用、停用 | 三个以上互斥状态 → Radio |
| 实验功能的灰度入口 | 同意协议等确认 → Checkbox |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 滑轨 Track | 灰底是关，品牌色是开 |
| 滑块 Thumb | 左右位置表达状态，切换带过渡动画 |
| 文案 Label | 写清控制的是什么 |
四种变体
| 变体 | 说明 |
|---|---|
| 开启 On | 功能当前处于打开状态 |
| 关闭 Off | 功能当前处于关闭状态 |
| 带文案 With Label | 设置页里，说清这个开关管什么 |
| 禁用 Disabled | 开关当前不可操作 |
常见问题
像手机设置里那样，这个功能一拨就开、再拨就关。
诊断题
设置页有 5 个开关，用户改了其中 3 个后离开页面，再回来发现全恢复了。问题在哪？
A. 开关应该是即时生效的——每次切换就保存，而不是等用户点"提交" B. 加一个"保存"按钮，用户改完所有开关后统一提交 C. 在离开页面时弹窗警告
如何告诉 AI Agent
请检查开关：每个开关切换后立即生效并给反馈（如 toast "已开启自动保存"）。不要给开关加统一的保存按钮——开关的意义就是即时生效。危险操作用按钮+确认弹窗，不要用开关。
来源：VibeHub · 开关
13. 滑块（Slider）
滑块是沿着一段连续或分级范围调整数值的表单控件。
音量、亮度和价格区间可用滑块调整。应显示范围、当前值并支持键盘操作；需要精确输入具体数值时，还要提供数字输入框 InputNumber。
Slider vs 精确数值选择
| 用 Slider | 用 InputNumber |
|---|---|
| 音量、亮度等连续调节 | 需要精确到个位的数值 |
| 价格区间筛选（双滑块） | 范围跨度很大，难以拖到目标值 |
| 调节程度、强度，允许近似选择 | 精确输入 50 这种具体值 |
| 拖动时实时预览效果 | 库存、价格等有明确意义的整数 |
什么时候不用 Slider
- 只有少量固定档位 → 直接用 Radio 列出
- 需要选择日期 → DatePicker
- 范围跨度极大（如 0-100000）→ 配合 InputNumber
Anatomy：四个组成部分
| 部分 | 说明 |
|---|---|
| 轨道 Track | 整段可选范围 |
| 已选部分 Fill | 显示当前已选范围 |
| 手柄 Handle | 可拖动，悬停时放大 |
| 当前值 Value | 拖动时实时跟着变 |
四种变体
| 变体 | 用途 |
|---|---|
| 默认 Default | 音量、亮度等连续量的调节 |
| 双滑块区间 Range | 框定起止范围，比如价格带 |
| 带刻度 With Marks | 帮用户对齐几个关键档位 |
| 禁用 Disabled | 该调节项当前不可用 |
常见问题
价格范围想用一根可以拖着走的滑杆来调。
诊断题
价格筛选滑块范围是 ¥0-¥100,000，用户想选 ¥500 左右，拖了半天才拖到 ¥487。怎么改进？
A. 滑块旁边配上 InputNumber，让用户可以直接输入精确数值 B. 把滑块轨道加长一倍 C. 去掉滑块，只留 InputNumber
如何告诉 AI Agent
请给滑块配上当前值的实时显示。范围跨度大时，在旁边加 InputNumber 让用户可以直接输入精确值。双滑块用于价格区间等起止范围。只有少量固定档位时不要用滑块，改用 Radio。
来源：VibeHub · 滑块
14. 评分（Rate）
评分控件是让用户在有顺序的等级中选择评价分值的表单控件。
商品评价常用五颗星表示满意程度，并应同时显示"4 分"等可读文字。星数、是否允许半分必须与实际评价规则一致。
Rating vs 相似场景
| 场景 | 用 Rating | 不用 Rating |
|---|---|---|
| 只需赞/不赞 | 用点赞/点踩按钮 | |
| 0~10 分推荐度 NPS | 使用与量表一致的数字选择 | |
| 需了解低分原因 | 配合 Textarea 收集文字反馈 | 只有星星没有文字 |
| 购买数量等精确数值 | 用 InputNumber |
什么时候用
| 场景 | 示例 |
|---|---|
| 订单、商品评价：交易后的标准动作 | 五星 + "满意" |
| 满意度调查：低成本收集反馈 | 请为本次服务评分 |
| 半星表达更细的程度 | 3.5 分 |
| 只读展示综合评分和评分人数 | 4.8 · 1234 条评价 |
Anatomy：三个组成部分
| 部分 | 说明 |
|---|---|
| 评分整体 Rate | 通常五颗，数量和图标都可换 |
| 星星 Star | 实心已选、空心未选，支持半颗 |
| 辅助文案 Text | 分值和对应感受，如"4 分 · 满意" |
四种变体
| 变体 | 用途 |
|---|---|
| 默认 Default | 五星制打分，表达几分满意 |
| 半星 Half Star | 想要更细的分数粒度时 |
| 只读展示 Readonly | 展示综合评分，不让用户改 |
| 自定义图标 Custom Icon | 品牌感，用爱心等图形替换星星 |
常见问题
想让用户给商品打个分，用星星就行。
诊断题
商品详情页显示评分 4.8 但没标注多少人打分。用户看到后觉得"只有 2 个人打了 5 分也能显示 4.8？"怎么改进？
A. 只读评分旁边显示样本量，如"4.8（1234 条评价）" B. 少于 10 条评价时不显示评分 C. 把所有评分四舍五入到整数
如何告诉 AI Agent
请给评分组件加上辅助文案（如"4 分 · 满意"）。只读展示时标注样本量。需要收集低分原因时，评分下方配合 Textarea。只有点赞/踩的需求时不要用五星评分。
来源：VibeHub · 评分
15. 选择器（Select）
选择器是从固定选项列表中选择一个或多个值的表单控件。
城市、部门等选项较多且不适合平铺时可收进选择器。只有少量选项时单选框 Radio 更直观；允许用户自定义内容时应使用输入框或自动完成 AutoComplete。
别名：下拉选择框 · Select Box
Select vs 易混淆控件
| 控件 | 区别 |
|---|---|
| 下拉菜单 Dropdown | Select 用来选一个表单值；Dropdown 展开的是操作或导航（重命名、导出、删除） |
| 自动完成 AutoComplete | Select 只能从固定选项选；AutoComplete 随输入给出建议，可自定义输入 |
| 单选框 Radio | 选项少且需直接比较 → Radio 平铺；选项多 → Select 收起来 |
| 级联选择器 Cascader | 省市区等有上下级关系 → Cascader |
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 值来自固定选项：状态、分类、优先级 | 选项少且需直接比较 → Radio 平铺 |
| 选项多、平铺不便：收进下拉列表 | 需要选多个 → Checkbox 或多选 Select |
| 列表页筛选条件：几个选择器排一排 | 选项有上下级 → Cascader |
| 选项文案较长：模板、文件等带描述 | 允许用户输入新值 → AutoComplete |
Anatomy：五个组成部分
| 部分 | 说明 |
|---|---|
| 触发框 Trigger | 平时收起来的样子，显示当前选中值 |
| 选中文案 Selected Label | 告诉用户现在选的是什么 |
| 下拉箭头 Caret | 表示内容可以展开，图标随展开状态变化 |
| 下拉面板 Dropdown | 显示所有选项的浮层，可以搜索和分组 |
| 选项 Option | 悬停高亮，选中项带对勾 |
五种变体
| 变体 | 用途 |
|---|---|
| 基础单选 Default | 选项固定、只选一个时的默认形态 |
| 多选 Multiple | 选项偏多又要同时选好几个时 |
| 可搜索 Searchable | 选项较多时，通过输入定位目标 |
| 可清空 Clearable | 筛选条件可选时，允许恢复为未选择 |
| 禁用 Disabled | 条件不满足时暂时禁用 |
常见问题
选项有几十个，全摆出来太占地方，收起来点一下再挑。
诊断题
表单让用户在 4 个固定、互斥的时区中选一个。哪种控件最合适？
A. 使用 Select，并显示当前已选时区 B. 使用任意文本输入，让用户自己拼写时区 C. 把四个同级操作都做成提交按钮
如何告诉 AI Agent
请把时区字段改成固定选项的 Select，保留当前值并为每个选项提供清楚名称。键盘选择一个新时区后保存，再刷新确认显示和已保存值一致。
16. 自动完成（AutoComplete）
自动完成是在用户输入时显示匹配建议、帮助更快完成输入的表单控件。
填写地址、联系人或标签时可从建议中点选，也可继续输入。最终能否提交未匹配内容取决于业务规则；只接受固定选项时要限制为选择建议，或改用选择器 Select。
别名：自动补全 · 输入建议
前置知识：输入框 + 选择器
AutoComplete vs 易混淆控件
| 控件 | 区别 |
|---|---|
| 选择器 Select | Select 只能从固定列表选；AutoComplete 随输入给建议，可自定义输入 |
| 组合框 Combobox | Combobox 是"输入框+弹出选项"的完整控件；AutoComplete 强调自动出现匹配建议的行为，两者常被混用 |
什么时候用 / 什么时候不用
| 用 | 不用 |
|---|---|
| 搜索框联想：输入关键词，实时给候选 | 固定枚举 → Select |
| 固定后缀补全：邮箱、网址等"半自由"输入 | 数据有层级关系 → Cascader |
| 历史记录快速重选：最近搜过用过的直接点 | 选项少且需直接比较 → Radio 平铺 |
| 命令面板：输入指令名快速执行操作 | 业务只接受已有数据，却允许未匹配内容提交 |
Anatomy：四个组成部分
| 部分 | 说明 |
|---|---|
| 输入框 Input | 用户打字的地方，和普通输入框一样 |
| 建议面板 Suggestion Panel | 跟随输入实时刷新候选 |
| 建议项 Suggestion | 一条候选，键盘上下可选 |
| 高亮片段 Matched Text | 命中的关键词加亮，说明为什么推荐 |
四种变体
| 变体 | 用途 |
|---|---|
| 搜索联想 Search Suggest | 搜索框里边打字边给候选词 |
| 邮箱后缀 Email Suffix | 邮箱、网址等半固定格式的输入 |
| 历史记录 History | 让用户一次点击重选最近搜过的内容 |
| 分组建议 Grouped | 候选来自不同类型时，按类型分组以便识别 |
常见问题
输入前几个字，下面自动猜我要写什么，点一下就补全。
诊断题
邀请成员时，用户可能从几千名员工里找"王小明"。哪种交互更合适？
A. 输入后给出匹配建议，选中一位已有员工再加入 B. 把所有员工放进一个很长的 Select C. 允许任意输入并直接创建一个同名新员工
如何告诉 AI Agent
成员邀请框请在输入至少两个字符后查询匹配员工，选择建议项后再发送邀请。测试无结果、同名候选和键盘选择：无结果要说明原因，同名项要有可区分信息，选中后提交的必须是员工 id。
17. 级联选择器（Cascader）
点开一个选项后继续选择下一级，常见于省、市、区选择。
用户先在一组选项里选中一项（如"广东省"），页面随即展开该选项下的子级选项（如广州、深圳等市），选中市后再展开区。整个流程是逐层、单向的——每一步的选择决定下一层显示什么。级联选择器的核心价值在于把有层级关系的数据拆成多步选择，降低单次选择的认知负担。
前置知识：选择器 Select
术语 vs 易混淆控件
| 术语 | 区别 |
|---|---|
| Cascader vs Select | Select 是单层下拉；Cascader 有多层联动展开 |
| Cascader vs TreeSelect | Cascader 是逐层单选路径；TreeSelect 支持多分支勾选 |
| Cascader vs Menu | Menu 用于导航跳转；Cascader 用于数据选择并回显 |
什么时候用 / 什么时候不用
| 用 Cascader | 不用 Cascader |
|---|---|
| 数据有明确的层级关系（省→市→区） | 数据只有一层 |
| 需要用户沿固定路径逐级选择 | 需要多分支勾选（用 TreeSelect） |
| 需要回显完整路径（如"广东省 / 广州市 / 天河区"） | 每层选项很少，可直接平铺 |
| 组织架构、商品类目等层级导航 | 用户需要跨层级自由选择 |
Anatomy：组成部分
| 部分 | 说明 |
|---|---|
| 触发框 Trigger | 显示当前选中路径的输入框 |
| 级联列 Column | 每一级展开的选项面板 |
| 选项 Option | 每列中可点击的具体条目 |
| 下级箭头 Arrow | 标识该选项有子级的展开指示器 |
变体
| 变体 | 场景 |
|---|---|
| 省市区 Region | 固定三级地址选择，中国标准省市区数据 |
| 完整路径回显 Path Echo | 触发框中显示完整路径（广东省 / 广州市 / 天河区） |
| 仅末级回显 Leaf Only | 触发框只显示最后一级（天河区） |
| 可搜索 Searchable | 允许输入关键词快速定位选项 |
常见问题
选地址那种，先选省、再选市、再选区，一层层点下去。
诊断题
用户说"选省市区的弹窗在手机上不好点，列太窄了"。以下哪种方案最合理？
A. 在移动端将级联选择器改为分步表单，每步一屏只选一级 B. 把三列挤在同一行，缩小字体 C. 让用户手动输入省市区文本
如何告诉 AI Agent
地址选择用级联选择器，数据源是中国标准省市区三级数据。PC 端三列并排展示，移动端改为分步选择（每步一屏）。选中后触发框中回显完整路径"省 / 市 / 区"，支持清除重选。
18. 树选择（TreeSelect）
在可展开的父子列表里勾选一个或多个项目。
例如设置数据权限时，用户可以展开"公司 → 部门 → 小组"，再跨不同部门勾选需要开放的范围。与级联选择器的关键区别：TreeSelect 支持多分支勾选，Cascader 只能沿一条路径选一个结果。
前置知识：树形控件 Tree · 复选框 Checkbox
术语 vs 易混淆控件
| 术语 | 区别 |
|---|---|
| TreeSelect vs Cascader | TreeSelect 可跨分支多选；Cascader 逐层单选一条路径 |
| TreeSelect vs Checkbox | Checkbox 是平铺列表无层级；TreeSelect 有父子嵌套关系 |
| TreeSelect vs Tree | Tree 只展示结构不做选择；TreeSelect 多了勾选和数据提交 |
什么时候用 / 什么时候不用
| 用 TreeSelect | 不用 TreeSelect |
|---|---|
| 按部门分配权限，跨部门勾选成员 | 只选一个叶子节点（用 Cascader） |
| 跨类目多选（服饰→男装→衬衫 + 家居） | 选项之间没有层级（用 Checkbox 平铺） |
| 需要父子联动——勾父节点自动带子节点 | 只需展示结构不需要选择（用 Tree） |
| 树太大需要先搜索再定位 | 数据没有真实父子关系，层级是硬编的 |
Anatomy：组成部分
| 部分 | 说明 |
|---|---|
| 触发框 Trigger | 用标签回显已勾选的节点 |
| 树面板 Tree Panel | 显示完整树状选项的浮层 |
| 父节点 Parent Node | 可展开收起，勾选通常带动子节点 |
| 勾选框 Checkbox | 标记选中，"半选"表示部分子项选中 |
| 子节点 Child Node | 缩进一级，体现从属关系 |
变体
| 变体 | 场景 |
|---|---|
| 单选树 Single | 层级数据里只挑一个节点 |
| 多选树 Multiple | 跨分支勾选多个节点 |
| 父子联动 Cascade Check | 勾选父级时自动同步整个分支 |
| 可搜索 Searchable | 树太大时先搜出目标节点再勾选 |
常见问题
选项是一层套一层的，得能展开再选。
诊断题
产品要求"选部门时勾选父部门自动选中所有子部门"。上线后用户投诉"我只想给父部门权限，不想带子部门"。以下哪种做法最合理？
A. 提供开关让用户自行选择是否联动，默认开启 B. 取消父子联动，强制用户手动勾选每个节点 C. 只保留 Cascader，禁止跨分支多选
如何告诉 AI Agent
部门权限选择用 TreeSelect，数据源为组织架构树。支持多选和父子联动（勾父节点自动带子节点），但提供关闭联动的选项。触发框用标签回显已选项，支持搜索定位和清除。注意处理半选状态：父节点部分子项选中时显示 indeterminate。
19. 日期选择器（DatePicker）
日期别让用户手输，给个日历直接挑。
日期选择器是用日历选择某一天或一段日期的表单控件。预订入住日期或筛选本月订单时可用日历降低格式歧义。需说明可选范围、区间是否包含当天；跨地区业务还必须说明计算日期的时区。
前置知识：输入框 Input
术语 vs 易混淆控件
| 术语 | 区别 |
|---|---|
| DatePicker vs TimePicker | DatePicker 选日期（某天/某段）；TimePicker 选时间（几时几分） |
| DatePicker vs Select | Select 适合粗粒度（如"最近一个月"）；DatePicker 需要精确到天 |
| DatePicker vs Checkbox | Checkbox 适合固定周几（每周一三五）；DatePicker 需要具体日期 |
什么时候用 / 什么时候不用
| 用 DatePicker | 不用 DatePicker |
|---|---|
| 选单个日期：生日、截止日期、预约日 | 让用户手输日期——格式五花八门容易写错 |
| 选一段时间：报表区间、酒店入住离店 | 只需选时间不选日期（用 TimePicker） |
| 有些日期不可选：过去的日子、已约满时段 | 仅需粗粒度范围如"最近一个月"（用 Select） |
| 提供快捷区间：今天、最近 7 天、最近 30 天 | 选每周固定日期如周一三五（用 Checkbox） |
Anatomy：组成部分
| 部分 | 说明 |
|---|---|
| 触发框 Trigger | 显示已选日期，格式统一 |
| 月份头部 Header | 切换年月的导航条 |
| 日期网格 Day Grid | 按每周 7 列排列，展示整月日期 |
| 日期格 Day Cell | 普通一天，悬停高亮 |
| 选中日 Selected Day | 当前选中的日期，实心高亮 |
变体
| 变体 | 场景 |
|---|---|
| 单日期 Single | 只需选一天，如生日或截止日期 |
| 范围选择 Range | 选开始和结束两天的一段区间 |
| 禁用日期 Disabled | 不可选日期提前以禁用状态说明限制 |
| 快捷选项 Shortcuts | 高频时间范围提供快捷按钮，减少逐日选择 |
常见问题
输入日期让人抓狂——格式对不上、日子写错、还不能一眼看出限制。
诊断题
海外用户反馈：选"7 月 21 日"提交后，后端记录的是 7 月 20 日。最可能的原因是什么？
A. 前端用本地时区，后端用 UTC，时区转换导致日期偏差 B. 用户浏览器缓存了旧版本日历组件 C. 数据库字段类型是字符串而非日期类型
如何告诉 AI Agent
日期选择用 DatePicker 组件。支持单选和范围选择，提供"今天/最近 7 天/最近 30 天"快捷选项。禁用过去日期（或按业务规则禁用特定日期）。触发框统一显示格式为 YYYY-MM-DD。跨时区业务需明确时区处理逻辑（用 UTC 存储，前端按用户时区展示）。
20. 时间选择器（TimePicker）
让用户选几点几分，别让他自己打字。
时间选择器是让用户从允许范围中选择具体时刻的表单控件。预约会议可选择 09:30 这类时间。应明确 12 小时制或 24 小时制、时间步长和不可选时段；跨地区协作还要显示时区。
前置知识：输入框 Input
术语 vs 易混淆控件
| 术语 | 区别 |
|---|---|
| TimePicker vs DatePicker | TimePicker 选时刻（几时几分）；DatePicker 选日期（某天/某段） |
| TimePicker vs Select | Select 适合粗粒度（"上午/下午"）；TimePicker 需要精确到分钟 |
| TimePicker vs 手输时间 | 手输格式不可控（"下午三点"）；TimePicker 结构化输出 HH:mm |
什么时候用 / 什么时候不用
| 用 TimePicker | 不用 TimePicker |
|---|---|
| 会议/日程的开始时间 | 还需要选日期——用 DatePicker 的日期时间模式 |
| 营业时间等时间段（开始+结束一对） | 只需上午/下午等粗粒度时段（用 Select） |
| 定时任务：每天几点自动执行 | 允许自由输入自然语言——系统难以稳定解析 |
| 按业务步长选择：预约每半小时一档 | 跨时区不标时区——相同时间在不同地区含义不同 |
Anatomy：组成部分
| 部分 | 说明 |
|---|---|
| 触发框 Trigger | 显示已选时间 |
| 时间列 Time Column | 小时、分钟各一列，可滚动 |
| 时间项 Time Option | 一个可选的时刻 |
| 选中项 Selected | 当前时间，居中高亮 |
变体
| 变体 | 场景 |
|---|---|
| 24 小时制 24-hour | 会议和定时任务，避免上午/下午歧义 |
| 12 小时制 12-hour | 面向习惯上午/下午说法的用户 |
| 时间范围 Range | 选开始和结束的一对时间（如营业时间 09:00→18:00） |
| 固定步长 Step | 按业务允许的时间间隔提供选项（每 30 分钟一档） |
常见问题
时间框滚半天才能找到想要的那一分钟，手输又怕格式不对。
诊断题
用户在美国设置定时推送为"09:00"，结果每天凌晨收到推送。最可能的原因是什么？
A. 时间以 UTC 存储但前端未标注时区，用户以为是本地时间 B. 推送服务性能差，延迟了 15 小时 C. 数据库时间字段溢出
如何告诉 AI Agent
时间选择用 TimePicker 组件。默认 24 小时制，步长 30 分钟。支持时间范围选择（开始+结束）。跨时区业务需明确标注时区，存储用 UTC，前端按用户时区转换展示。不可选时段（如午休）以禁用状态呈现。
21. 上传（Upload）
用户要能把自己的图片传上来。
让用户从电脑或手机选择图片、视频或文档，并提交给当前网站或软件。例如更换头像时，页面应先说明支持的格式和大小，选择图片后显示上传进度、成功或失败。服务端仍要再次检查文件是否安全、格式是否正确。
别名：文件上传 · 上传控件
前置知识：表单 Form
术语 vs 易混淆控件
| 术语 | 区别 |
|---|---|
| Upload vs File | Upload 负责选择、传输和失败重试；File 展示已存在或正在处理的文件 |
| Upload vs Input | Input 填文本（如文件 URL）；Upload 处理本地文件选择和上传 |
什么时候用 / 什么时候不用
| 用 Upload | 不用 Upload |
|---|---|
| 拖拽上传：适合大文件或批量选择 | 用户只有文件链接——用 Input 填写 URL |
| 图片上传带预览：头像、封面传完马上看到 | 大量小文件逐个上传——先打包或支持选择文件夹 |
| 文件列表+进度：多个文件各自状态清楚 | 失败不给重试——传到 99% 失败只能从头再来 |
| 写清格式和大小限制：传之前就知道行不行 | 不设大小上限——大文件传半小时才报错 |
Anatomy：组成部分
| 部分 | 说明 |
|---|---|
| 拖拽区 Drop Zone | 虚线框，拖文件进来或点击选择 |
| 限制说明 Hint | 格式、大小上限，提前说清 |
| 文件项 File Item | 一个文件一行，可删除、可重试 |
| 文件名 File Name | 显示文件叫什么 |
| 进度条 Progress | 传到哪了一目了然 |
变体
| 变体 | 场景 |
|---|---|
| 拖拽区 Drag | 上传大文件或批量选择文件时 |
| 按钮触发 Button | 页面空间有限，用按钮打开文件选择器 |
| 图片卡片 Picture | 上传头像或封面，需展示已选图片 |
| 文件列表 List | 同时上传多个文件，需分别显示处理进度 |
常见问题
用户传了个 4K 视频，等了十分钟才报"文件太大"——限制应该在上传前就说清楚。
诊断题
用户上传头像成功，但刷新后头像又变回默认图。最可能的原因是什么？
A. 前端显示上传成功，但保存接口没正确关联头像 URL 到用户记录 B. 浏览器缓存了旧头像 C. 图片格式不支持
如何告诉 AI Agent
上传组件支持拖拽和点击选择，限制说明写清格式（JPG/PNG）和大小上限（如 10MB）。上传过程中显示每个文件的进度条，支持取消和失败重试。上传完成后服务端需校验文件类型和大小（前端限制可被绕过）。上传成功后回显预览（图片）或文件名+状态。
来源：VibeHub · 上传