TinyRobot SuggestionPopover 智能建议弹出框组件

TinyRobot SuggestionPopover：智能建议弹出框组件

在AI对话界面中，用户真正需要的是更自然的引导方式。当AI助手准备提供一组可选建议时，一个恰到好处的弹出框既能承载足够的信息密度，又不会让操作变得繁琐。SuggestionPopover正是为这种场景量身打造——点击触发器，浮层展开，建议列表清晰呈现，用户一眼就能找到目标，一键即可选中。

该组件的核心价值体现在以下几个方面：

• 引导式交互：将建议项集中在弹出框中，界面简洁不杂乱
• 上下文帮助：在对话流程的恰当时机提供选项，不脱离上下文
• 灵活的数据结构：既支持平铺列表，也支持分组列表，按需使用
• 丰富的自定义：触发器、列表项、头部、内容区等插槽一应俱全
• 状态管理：loading和empty状态默认内置，无需额外处理
• 移动端适配：窗口宽度小于768px时自动切换为移动端样式，省心省力

基本用法：带数据的弹出框

通过data属性传入建议数据，再用trigger插槽自定义触发器。点击按钮即可弹出列表，操作直接明了。

触发方式：click vs manual

SuggestionPopover提供两种触发方式，通过trigger属性配置：

• 'click'（默认）：点击触发器时自动弹出或关闭，省心省力
• 'manual'：需配合show属性（支持v-model）手动控制显示和隐藏，适用于需要精确控制的场景

manual模式的应用场景很典型——例如当AI回复完成后，需按业务逻辑自动弹出建议，此时手动控制便派上用场。

分组建议数据

当建议项数量较多、类别明确时，分组数据格式能有效提升展示效果。在data数组中传入SuggestionGroup对象，通过group字段标识分组，items字段包含该分组下的建议项，用户一目了然。

注意：分组数据和普通数据不能混用——data数组中的项要么全是SuggestionItem，要么全是SuggestionGroup，二选一。

selectedGroup支持v-model，可设置默认选中分组，也能在用户切换时获取当前分组。groupShowMoreTrigger属性控制分组“显示更多”的触发方式，支持'click'和'hover'，按需选用。

自定义列表项渲染

通过item插槽，每个建议项的渲染完全由你掌控。插槽参数为{ item }，可在SuggestionItem中添加任意自定义字段，按需展开展示风格。

加载和空状态

SuggestionPopover内置了loading和empty两种状态。通过loading属性可显式开启加载状态；当data为空数组时，自动显示空状态。两种状态均提供对应插槽（loading和empty），可按需修改显示内容。

Header 和 Body 插槽

除item、loading、empty外，SuggestionPopover还提供header和body插槽，用于完全接管弹出框的头部和内容区。其内部结构如下：

+---------------------------+
|     SuggestionPopover     |
|  +---------------------+  |
|  |       header        |  |
|  +---------------------+  |
|  |                     |  |
|  |        body         |  |
|  |   +-------------+   |  |
|  |   |   item[]    |   |  |
|  |   +-------------+   |  |
|  |                     |  |
|  |  loading / empty    |  |
|  +---------------------+  |
+---------------------------+

• 使用header插槽时，会替换默认的标题区域
• 使用body插槽时，会替换整个列表区域（包括item列表、loading和empty状态）

移动端适配

SuggestionPopover自带移动端适配逻辑。当视窗宽度小于768px时，弹出框自动切换为移动端友好的展示样式——触控区域更大，布局更适合小屏幕。通常无需额外处理，只需确保页面配置正确的viewport即可：

<meta name="viewport" content="width=device-width, initial-scale=1.0" />

API 参考

Props

属性	类型	必填	默认值	说明
data	SuggestionData	是	-	建议数据
title	string	否	-	弹出框标题
icon	VNode | Component	否	-	标题图标
show	boolean	否	-	控制弹出框显示/隐藏，仅在 trigger 为 'manual' 时有效
trigger	'click' | 'manual'	否	'click'	触发方式：点击或手动控制
selectedGroup	string	否	-	当前选中分组，支持 v-model
groupShowMoreTrigger	'click' | 'hover'	否	-	分组"显示更多"的触发方式
loading	boolean	否	false	是否显示加载状态
topOffset	number	否	-	顶部偏移量

Slots

插槽名	类型	说明
trigger	() => VNode | VNode[]	自定义触发器
item	({ item }: { item: SuggestionItem }) => VNode | VNode[]	自定义渲染列表项
loading	() => VNode | VNode[]	自定义加载状态显示
empty	() => VNode | VNode[]	自定义空状态显示
header	() => VNode | VNode[]	自定义头部区域
body	() => VNode | VNode[]	自定义列表区域

Events

事件名	参数	说明
item-click	item: SuggestionItem	点击建议项时触发
group-click	group: SuggestionGroup	点击分组时触发
open	-	弹窗打开时触发
close	-	弹窗关闭时触发
click-outside	event: MouseEvent	点击弹窗外部区域时触发

Types

interface SuggestionItem {
  id: string
  text: string
}interface SuggestionGroup {
  group: string
  label: string
  icon: VNode | Component
  items: SuggestionItem[]
}type SuggestionData = (SuggestionItem | SuggestionGroup)[]

---

OpenTiny NEXT是一套企业智能前端开发解决方案，以生成式UI和WebMCP两大核心技术为基础，对现有传统的TinyVue组件库、TinyEngine低代码引擎等产品进行智能化升级，构建出面向Agent应用的前端NEXT-SDKs、AI Extension、TinyRobot智能助手、GenUI等新产品，加速企业应用的智能化改造，实现AI理解用户意图自主完成任务。