---
title: "PromptBar 提示条"
description: "内联 @ 数据源、/ 命令与模型选择的紧凑输入条"
category: AiChat
status: beta
since: 0.3.9
tags: [ai, composer, prompt, mention, command]
syncStatus: reviewed
verified: true
---

## 用法

### 完整输入条
输入 `@` 打开数据源，`/` 打开命令；↑↓ 移动，Enter 或 Tab 确认，Esc 收起。
:::TuffDemoWrapper{demo="PromptBarPromptBarDemo" code-lang="vue" description="Rounded 与 Pill 两种形态"}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const draft = ref('')
  const model = ref('sprinkles')
  const listening = ref(false)
  const attachments = ref([])

  const sources = [
    { key: 'attach', name: 'Add photos & files', desc: 'Upload from your computer', attach: true },
    { key: 'gmail', name: 'Gmail', desc: 'Read and manage Gmail', connectable: true },
  ]
  const commands = [{ key: 'compare', name: '/compare', desc: 'Flavor vs. last summer' }]
  const models = [
    { key: 'sprinkles', name: 'Sprinkles 5', tag: 'Flagship' },
    { key: 'vanilla', name: 'Vanilla 1', tag: 'Basic' },
  ]
  </script>

  <template>
    <TxPromptBar
      v-model="draft"
      v-model:model="model"
      v-model:listening="listening"
      :sources="sources"
      :commands="commands"
      :models="models"
      :attachments="attachments"
      dictatable
      @attach="pickFiles"
      @attachment-remove="removeAttachment"
      @send="submit"
    />
  </template>
---
:::

### 最佳实践

- 附件是受控的：`send` 后组件只清文本，附件由宿主清空；要等本轮受理后再清文本时，设 `clearOnSend: false`。
- 听写只呈现状态；识别在宿主完成，结果用 `insert()` 或 `v-model` 写回草稿。
- 品牌图标走 `#source-icon` 插槽，组件不内置第三方 SVG。
- 菜单相对输入条绝对定位，会被祖先的 `overflow: hidden` 裁切且不翻转；不要把输入条放进会裁剪的滚动容器。
- 只要块状输入框、不需要菜单时，用 [ChatComposer 消息输入](/docs/dev/components/chat-composer)（`TxChatComposer`）。

## API 参考

### 属性

| 属性名 | 类型 | 默认值 | 说明 |
|------|------|---------|------|
| `modelValue` | `string` | — | 草稿文本；不绑定时组件自持。 |
| `variant` | `'rounded' \| 'pill'` | `'rounded'` | 外壳与控件的圆角形态。 |
| `placeholder` | `string` | `'Write a message…'` | 占位文本，也是可访问名称的兜底。 |
| `ariaLabel` | `string` | — | 输入框的可访问名称；缺省时用 `placeholder`。 |
| `disabled` | `boolean` | `false` | 禁用整条输入条。 |
| `submitting` | `boolean` | `false` | 上一轮仍在进行：只拦发送，不拦输入。 |
| `sources` | `PromptBarSource[]` | — | `@` 菜单的行；不传时同时隐藏 + 按钮。 |
| `commands` | `PromptBarCommand[]` | — | `/` 菜单的行；`name` 自带前导斜杠。 |
| `attachments` | `AiAttachment[]` | `[]` | 展示用附件；上传与增删由宿主负责。 |
| `models` | `PromptBarModel[]` | `[]` | 模型列表；为空时不渲染模型按钮。 |
| `model` | `string` | 第一项 | 选中的模型 key，配合 `v-model:model`。 |
| `dictatable` | `boolean` | `false` | 渲染听写按钮。 |
| `listening` | `boolean` | — | 听写状态，配合 `v-model:listening`；识别在宿主。 |
| `listeningPlaceholder` | `string` | `'Listening…'` | 听写期间的占位文本。 |
| `minHeight` | `number` | `28` | 输入框折叠高度（px）。 |
| `maxHeight` | `number` | `100` | 增高上限（px），超过后内部滚动。 |
| `sendOnEnter` | `boolean` | `true` | Enter 发送，Shift+Enter 换行。 |
| `allowEmptySend` | `boolean` | `false` | 允许无文本也无附件时发送。 |
| `clearOnSend` | `boolean` | `true` | 发送后清空草稿；关闭时文本保留，由宿主清空。 |
| `sourcesHintText` | `string` | `'Type to search sources & files'` | `@` 菜单无查询词时的提示文案。 |
| `commandsHintText` | `string` | `'Type to search commands'` | `/` 菜单无查询词时的提示文案。 |
| `emptyTextFormatter` | `(query: string) => string` | `` `` (query) => `No matches for "${query}"` `` `` | 菜单没有匹配时的文案，参数为查询词。 |
| `connectText` | `string` | `'Connect'` | 未连接的可连接行上的按钮文字。 |
| `connectedText` | `string` | `'Connected'` | 已连接的可连接行上的文字。 |
| `sendLabel` | `string` | `'Send'` | 发送键的可访问名称。 |
| `attachLabel` | `string` | `'Add attachments and sources'` | 附件按钮的可访问名称。 |
| `modelLabel` | `string` | `'Choose model'` | 模型按钮的可访问名称。 |
| `startDictationLabel` | `string` | `'Start dictation'` | 未听写时听写按钮的可访问名称。 |
| `stopDictationLabel` | `string` | `'Stop dictation'` | 听写进行中时听写按钮的可访问名称。 |
| `attachmentFallbackLabel` | `string` | `'Attachment'` | 没有名称的附件所显示的胶囊文字。 |
| `removeAttachmentLabelFormatter` | `(name: string) => string` | `` `` (name) => `Remove ${name}` `` `` | 附件删除按钮的可访问名称，参数为附件名。 |

文案 props 均有英文默认值，可逐个覆盖，见上表。

`PromptBarSource` 为 `{ key, name, desc?, attach?, connectable?, connected? }`；`PromptBarCommand` 为 `{ key, name, desc? }`；`PromptBarModel` 为 `{ key, name, tag? }`。

### 事件

| 事件名 | 参数 | 说明 |
|------|------|------|
| `update:modelValue` | `(value: string)` | 草稿变化时触发。 |
| `update:model` | `(key: string)` | 选中模型变化时触发。 |
| `update:listening` | `(listening: boolean)` | 切换听写时触发。 |
| `send` | `({ text, attachments })` | 发送时触发；默认清空文本（见 `clearOnSend`），附件由宿主清空。 |
| `attach` | `()` | 选中「添加附件」行时触发，宿主打开文件选择器。 |
| `attachmentRemove` | `(id: string)` | 点击附件胶囊的删除时触发。 |
| `attachmentAdd` | `(files: File[])` | 粘贴或拖入文件时触发。 |
| `sourceSelect` | `(source: PromptBarSource)` | 插入提及后触发。 |
| `commandSelect` | `(command: PromptBarCommand)` | 插入命令后触发。 |
| `connectToggle` | `(source: PromptBarSource)` | 激活未连接的可连接行时触发。 |
| `paste` | `(event: ClipboardEvent)` | 原始粘贴事件，不阻止默认行为。 |
| `focus` | `(event: FocusEvent)` | 输入框获得焦点时触发。 |
| `blur` | `(event: FocusEvent)` | 输入框失去焦点时触发。 |

### 插槽

| 插槽名 | 作用域参数 | 说明 |
|------|------|------|
| `source-icon` | `{ source }` | `@` 行的前置图标（22×22）。 |
| `attachments` | `{ attachments }` | 替换整个附件胶囊区。 |
| `actions` | `{ send, canSend }` | 插在发送键之前的自定义控件。 |

### 暴露方法

| 名称 | 类型 | 说明 |
|------|------|------|
| `focus` | `() => void` | 聚焦输入框。 |
| `insert` | `(text: string) => void` | 在草稿末尾插入文本，必要时补空格。 |
| `closeMenus` | `() => void` | 关闭 + 菜单与模型菜单。 |
| `menuOpen` | `boolean` | 是否有菜单展开，只读。 |

## 令牌菜单单独使用

`@` / `/` 的解析与菜单状态机以 `useTokenMenu` 单独导出，不碰 DOM，可为自有输入框加提及。

```ts
import { parseToken, useTokenMenu } from '@talex-touch/tuffex/prompt-bar'

const draft = ref('')
const { menu, rows, activeIndex, engaged, move, engage, dismiss, insert } = useTokenMenu({
  draft,
  sources,
  commands,
})

// 选中一行：把待定令牌替换成插入文本，返回新的草稿
draft.value = insert(`@${row.name}`)
```

数据源按名称子串匹配，命令去掉前导斜杠后按前缀匹配（`/comp` 只留 `/compare`）。`parseToken` 只认词边界后的行尾令牌，`you@host` 不会被当成提及。

## 概述

- 输入法组字期间，Enter 只确认候选词，不发送，也不选中菜单行。
- 菜单采用 combobox 模式：输入框为 `role="combobox"` 并带 `aria-activedescendant`，菜单为 `listbox`；没有可提及内容时退化为普通文本框。
- 高亮只在悬停或按过方向键后出现，首次 ↑ / ↓ 落在列表两端；点按菜单行不会让输入框失焦。
- 可连接但未连接的行，激活时派发 `connectToggle` 而不插入提及；连接后再激活才插入。
- 点击外部或按 Esc 关闭菜单；Esc 只在确实关闭了菜单时才被拦截，否则冒泡给宿主。聚焦中的发送键或整条输入条被禁用时，焦点移到输入框（光标不动）或输入条根节点，不会掉到 `<body>`。
- 减少动态效果时弹入与按压动画停止，听写的三根条定格而不消失。

## 技术实现

- 移植自 [Beautiful UI](https://www.beautifului.dev)（© 2026 Shane Levine，MIT）。
- 控件行按自身宽度在单行与两行之间切换；新宽度在下一帧才写入，不在 `ResizeObserver` 回调里改布局。
- 源码：`packages/tuffex/packages/components/src/prompt-bar/`。

<TuffDocSourceLink />
