---
title: Suggestion Chips
description: 一键发起追问的建议胶囊
category: AiChat
status: beta
since: 0.3.9
tags: [ai, suggestion, chips]
syncStatus: reviewed
verified: true
---

## 用法

### 基础
::::TuffDemoWrapper{demo="SuggestionChipsSuggestionChipsDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const suggestions = ref([
    { id: 'explain', text: '解释这段代码' },
    { id: 'test', text: '补充单元测试' },
    { id: 'perf', text: '还有优化空间吗？' },
  ])

  function handleSelect(suggestion: { id: string, text: string }) {
    console.log(suggestion.id)
  }
  </script>

  <template>
    <TxSuggestionChips :suggestions="suggestions" @select="handleSelect" />
  </template>
---
::::

### 纵向追问列表
`layout="list"` 把胶囊改为带分隔线、行首有折返箭头的纵向行。
:::TuffDemoWrapper{demo="AiSuiteStreamingAnswerDemo" code-lang="vue" description="正文流完后，追问与来源一起变为可用"}
---
code: |
  <template>
    <p class="text-[12px] font-medium">追问</p>
    <TxSuggestionChips :suggestions="followUps" layout="list" @select="ask" />
  </template>
---
:::

### 最佳实践

- 一次给出 3–5 条建议。
- 文案写成用户会说的话（「补充单元测试」），不写功能名（「测试生成」）。
- 点击后清空或替换建议列表，避免重复发送。
- `id` 用稳定标识而非文案，便于统计与去重。
- 答案定稿后用 `layout="list"` 收尾。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `suggestions` | `AiSuggestion[]` | — | 建议列表，元素为 `{ id: string, text: string }`；必填。 |
| `layout` | `'wrap' \| 'list'` | `'wrap'` | `list` 改为带分隔线与折返箭头的纵向行。 |

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `select` | `(suggestion: AiSuggestion)` | 点击胶囊时触发，携带完整的建议对象。 |

## 概述

- `suggestions` 为空时不渲染。
- 每个胶囊以 `id` 作 key，同组内 `id` 必须唯一。
- 组件不维护选中态，点击后也不移除建议。
- `wrap` 溢出时横向滚动，滚动条隐藏，两侧渐变遮罩提示可滚动。
- `list` 的各行按位置错峰浮现（每行 90ms）；减少动态效果时直接显示。
- 容器为 `role="list"`、胶囊为 `role="listitem"`，覆盖了按钮的隐式语义；需要按钮语义时在外层补充说明文字。

## 技术实现

- 列表行的错峰入场由 CSS 动画延迟完成：每行的 `--tx-suggestion-chips-index` 乘以 90 毫秒，不用脚本计时。
- `wrap` 布局两侧的渐变遮罩由 `mask-image` 实现。
- 源码：`packages/tuffex/packages/components/src/suggestion-chips/`。

<TuffDocSourceLink />
