@fv-ui/ai-chat 1.7.3 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,1014 +1,1422 @@
1
- # @fv-ui/ai-chat
2
-
3
- ![version](https://img.shields.io/badge/version-1.0.0-blue)
4
- ![vue](https://img.shields.io/badge/vue-%5E3.4.0-brightgreen)
5
- ![element-plus](https://img.shields.io/badge/element--plus-%5E2.7.0-blue)
6
-
7
- 基于 Vue 3 + Element Plus 的 AI 对话组件库,复刻 element-plus-x 与 open-webui 对话框:从底层气泡、发送框、Markdown 渲染,到上层的对话整框(`<FvAiChat>`)、分支树消息、Artifacts 预览,一次给全。
8
-
9
- - 14 个基础组件(Bubble/Sender/Markdown/Thinking/...)自由拼装
10
- - 对话应用层整框 `<FvAiChat>`:顶栏模型多选、消息列表、分支切换、Artifacts 面板、发送停止一体化
11
- - 树形消息模型(同构 open-webui):一条提问可挂多个模型回答,分支可切换、可重生成
12
- - `ChatAdapter` 适配器协议:内置 OpenAI 兼容实现,可替换自研后端/Ollama
13
- - 流式打字机、思考链折叠、KaTeX/代码高亮(Prism)开箱即用
14
-
15
- ## 安装
16
-
17
- ```bash
18
- pnpm add @fv-ui/ai-chat
19
- ```
20
-
21
- peerDependencies:`vue ^3.4.0`、`element-plus ^2.7.0`、`@element-plus/icons-vue ^2.3.0`。
22
-
23
- ## 快速开始
24
-
25
- ```ts
26
- // main.ts —— 需要先引入 element-plus(组件库依赖其组件与暗色变量)
27
- import ElementPlus from 'element-plus'
28
- import 'element-plus/dist/index.css'
29
- import { createApp } from 'vue'
30
- import App from './App.vue'
31
-
32
- createApp(App).use(ElementPlus).mount('#app')
33
- ```
34
-
35
- ```vue
36
- <!-- App.vue -->
37
- <script setup lang="ts">
38
- import { FvAiChat } from '@fv-ui/ai-chat'
39
- import '@fv-ui/ai-chat/dist/style.css'
40
- </script>
41
-
42
- <template>
43
- <FvAiChat
44
- title="AI 助手"
45
- base-url="https://api.deepseek.com/v1"
46
- api-key="sk-xxx"
47
- model="deepseek-chat"
48
- style="height: 600px"
49
- />
50
- </template>
51
- ```
52
-
53
- `<FvAiChat>` 未传 `adapter` 时,用 `baseURL`/`apiKey`/`model` 构造内置 `OpenAIAdapter`(走 `/chat/completions`,SSE 流式)。两个都缺省时发送会报"未配置 adapter 或 baseURL"。
54
-
55
- ### Vite 项目必读:排除依赖预打包
56
-
57
- 内置头像/欢迎页 GIF 在 es 产物中以 `new URL(..., import.meta.url)` 按需引用。Vite dev server 默认把依赖交给 esbuild 预打包(optimizeDeps),而预打包**不会复制**该类资产——GIF 404 不显示(已知限制 [vitejs/vite#8427](https://github.com/vitejs/vite/issues/8427))。需在 `vite.config.ts` 排除预打包,让本包走源码 ESM 管线:
58
-
59
- ```ts
60
- // vite.config.ts
61
- export default defineConfig({
62
- optimizeDeps: {
63
- // @fv-ui/ai-chat:es 产物内置 GIF 以 new URL(..., import.meta.url) 引用,
64
- // esbuild 预打包不复制该类资产(vitejs/vite#8427),须排除预打包走源码 ESM 管线
65
- exclude: ['@fv-ui/ai-chat']
66
- }
67
- })
68
- ```
69
-
70
- 说明:仅 Vite **dev** 需要;生产 `build` 走 Rollup 管线会自动把 GIF 复制进产物并重写路径,不受影响。UMD(`<script>` 直用 `lib/index.js`)不涉及。
71
-
72
- ## 基础组件层 API
73
-
74
- ### FvMarkdown
75
-
76
- Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
77
-
78
- | Prop | 类型 | 默认 | 说明 |
79
- | --- | --- | --- | --- |
80
- | content | string | —(必填) | Markdown 源文本 |
81
- | mdPlugins | PluginWithParams[] | — | 额外 markdown-it 插件 |
82
- | highlight | (str, lang) => string | 内置 Prism | 自定义代码高亮 |
83
- | isTyping | boolean | — | 打字机模式样式钩子(透传占位) |
84
- | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(fence 原始 lang 命中列表时注入预览按钮,点击行为由消费方事件委托实现) |
85
- | tableToolbar | boolean | true | 表格工具栏:表格上方注入复制(复制表格 markdown 源文本)/下载(导出 CSV,带 BOM)单图标按钮 |
86
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
87
-
88
- | Ref | 说明 |
89
- | --- | --- |
90
- | getHtml() | 取当前渲染后的 HTML 字符串 |
91
-
92
- ### Typewriter
93
-
94
- 打字机输出,支持续打/重打/雾化遮罩。
95
-
96
- | Prop | 类型 | 默认 | 说明 |
97
- | --- | --- | --- | --- |
98
- | content | string | —(必填) | 全文(流式时增量传入,子集扩展自动续打) |
99
- | isMarkdown | boolean | false | 走 FvMarkdown 渲染(此时 suffix 不追加) |
100
- | isFog | boolean \| { bgColor?; width? } | false | 打字中尾部雾化遮罩 |
101
- | typing | boolean \| { step?; interval?; suffix? } | false | 开启打字机;对象形态可配步长/间隔/光标后缀 |
102
- | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(isMarkdown 模式透传 Markdown) |
103
- | locale | LocaleInput | undefined | 语言包(透传内嵌 Markdown 的代码块「预览」按钮文案) |
104
-
105
- | Event | 说明 |
106
- | --- | --- |
107
- | start / writing / finish | 开始打字 / 每次推进 / 全部打完 |
108
-
109
- | Ref | 说明 |
110
- | --- | --- |
111
- | interrupt() / continue() / restart() / destroy() | 暂停 / 继续 / 重打 / 重置清空 |
112
- | renderedContent / isTyping / progress | 已输出文本 / 是否打字中 / 进度 0-1 |
113
-
114
- ### Bubble
115
-
116
- 单条气泡(内部按需挂载 Typewriter/Markdown)。
117
-
118
- | Prop | 类型 | 默认 | 说明 |
119
- | --- | --- | --- | --- |
120
- | content | string | '' | 气泡内容 |
121
- | placement | 'start' \| 'end' | 'start' | start 靠左 / end 靠右 |
122
- | loading | boolean | false | 加载态(三点动画,可被 #loading 覆盖) |
123
- | typing | boolean \| TypingConfig | false | 打字机模式(透传 Typewriter) |
124
- | isMarkdown | boolean | false | 内容按 Markdown 渲染 |
125
- | isFog | boolean \| { bgColor?; width? } | false | 雾化(自定义气泡背景时传 bgColor) |
126
- | variant | 'filled' \| 'borderless' \| 'outlined' \| 'shadow' | 'filled' | 气泡样式 |
127
- | shape | 'round' \| 'corner' | 'round' | 圆角 / 方角 |
128
- | avatar | string | '' | 头像图片地址 |
129
- | avatarSize | ElAvatar size \| number | '' | 头像尺寸 |
130
- | avatarGap | string | '12px' | 头像与内容间距 |
131
- | avatarShape | 'circle' \| 'square' | 'circle' | 头像形状 |
132
- | avatarIcon | Component | — | 头像图标(与 avatar 冲突时优先) |
133
- | avatarSrcSet / avatarAlt | string | '' / '' | 头像 srcSet/alt |
134
- | avatarFit | 'fill' \| 'contain' \| 'cover' \| 'none' \| 'scale-down' | 'cover' | 头像填充方式(el-avatar fit) |
135
- | noPadding | boolean | false | 内容区去内边距 |
136
- | noStyle | boolean | false | 去气泡样式(透明/无框/无阴影) |
137
-
138
- | Event | 说明 |
139
- | --- | --- |
140
- | avatar-error | 头像加载失败 |
141
- | start / writing / finish | typing 模式下的打字机事件透传 |
142
-
143
- | Slot | 说明 |
144
- | --- | --- |
145
- | avatar / header / content / loading / footer | 自定义头像 / 头部 / 内容(优先于 content prop)/ 加载态 / 底部 |
146
-
147
- | Ref | 说明 |
148
- | --- | --- |
149
- | interrupt / continue / restart / destroy | Typewriter 方法转发(非 typing 模式为 no-op) |
150
- | renderedContent / isTyping / progress | Typewriter 状态转发 |
151
- | twInstance | 内部 Typewriter 原始实例(BubbleList @complete 透传用) |
152
-
153
- ### BubbleList
154
-
155
- 气泡列表 + 吸底/回底按钮。
156
-
157
- | Prop | 类型 | 默认 | 说明 |
158
- | --- | --- | --- | --- |
159
- | list | BubbleListItemProps[] | [] | 列表项(Bubble props + 必填 key) |
160
- | maxHeight | string | '' | 滚动容器最大高度(如 '350px'/'60vh') |
161
- | alwaysShowScrollbar | boolean | false | 始终显示滚动条 |
162
- | showBackButton | boolean | true | 是否显示回底按钮 |
163
- | backButtonThreshold | number | 80 | 距底超过该像素显示回底按钮 |
164
- | btnLoading | boolean | false | 回底按钮加载态 |
165
- | btnColor | string | '' | 回底按钮颜色(el-button color) |
166
- | backButtonPosition | { bottom?; left? } | {} | 回底按钮位置偏移 |
167
- | btnIconSize | number | 16 | 回底按钮图标尺寸 |
168
- | triggerIndices | 'only-last' \| 'all' \| number[] | 'only-last' | @complete 触发索引 |
169
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
170
-
171
- | Event | 说明 |
172
- | --- | --- |
173
- | complete | (typewriterInstance, index) 打字完成(按 triggerIndices 过滤后上抛) |
174
-
175
- | Slot | 说明 |
176
- | --- | --- |
177
- | avatar / header / content / loading / footer | 透传给每个 Bubble,作用域 { item, index } |
178
-
179
- | Ref | 说明 |
180
- | --- | --- |
181
- | scrollToTop() / scrollToBottom() / scrollToBubble(index) | 滚动控制 |
182
-
183
- ### Sender
184
-
185
- 输入发送框。
186
-
187
- | Prop | 类型 | 默认 | 说明 |
188
- | --- | --- | --- | --- |
189
- | modelValue | string(v-model) | '' | 输入值(缺省内部自持) |
190
- | placeholder | string | '' | 占位文案(缺省回落语言包 sender.inputPlaceholder) |
191
- | autosize | { minRows?; maxRows? } | { minRows: 3, maxRows: 7 } | 自增高(行高 22px;默认 3 行起步,内容多时自动加高至最多 7 行后内部滚动;显式传 {} 退回固定单行) |
192
- | submitType | 'enter' \| 'shiftEnter' \| 'cmdOrCtrlEnter' \| 'altEnter' | 'enter' | 提交按键模式 |
193
- | loading | boolean | false | 加载态(发送键变停止键,输入区禁用;停止键出现后 600ms 降险窗口内不可停,吸收发送瞬间的快速连点) |
194
- | disabled | boolean | false | 禁用(阻断提交) |
195
- | readOnly | boolean | false | 只读 |
196
- | clearable | boolean | false | 显示清空按钮 |
197
- | round | boolean | true | 主按钮(发送/停止)为圆形(element-plus circle;false 时方按钮,停止键光带沿方框流转) |
198
- | shadow | boolean | false | 输入区阴影效果(浮起感,聚焦时加深) |
199
- | inputWidth | string | '' | 输入区宽度(variant=default 时有效) |
200
- | variant | 'default' \| 'updown' | 'default' | default 同排 / updown 上输入下操作栏 |
201
- | submitBtnDisabled | boolean | false | 附加禁用发送按钮 |
202
- | triggerStrings | string[] | [] | 指令触发串(光标前命中弹指令框) |
203
- | triggerPopoverVisible | boolean(v-model:triggerPopoverVisible) | false | 指令弹框显隐 |
204
- | triggerPopoverWidth / triggerPopoverLeft | string | '' | 指令弹框宽度 / left 偏移 |
205
- | triggerPopoverOffset | number | 0 | 弹框距触发字符偏移量 |
206
- | triggerPopoverPlacement | ElPopover placement | 'top-start' | 弹框位置 |
207
- | allowSpeech | boolean | false | 开启语音输入:麦克风按钮 → 录音条(波形+时长,Esc 取消)→ 确认后转写文本插入光标处;浏览器 SpeechRecognition 实时转写 |
208
- | allowEmptySubmit | boolean | false | 允许空内容提交(附件场景:只发文件不输文字) |
209
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
210
-
211
- | Event | 说明 |
212
- | --- | --- |
213
- | update:modelValue / change | 输入值变化 |
214
- | submit | (value) 提交(提交后内部清空) |
215
- | cancel | 点击停止按钮(loading 翻 true 后 600ms 内的点击被吞不发——防连点误停) |
216
- | trigger | (keyword, visible) 命中指令串 |
217
- | recording-change | 语音录制状态变化(预留) |
218
- | paste-file | (file) 粘贴文件 |
219
- | update:triggerPopoverVisible | 指令弹框显隐同步 |
220
-
221
- | Slot | 说明 |
222
- | --- | --- |
223
- | header / footer | 头部/底部(配合 ref.openHeader/closeHeader) |
224
- | prefix | 输入区前缀 |
225
- | action-list | 自定义操作区(存在时隐藏内置按钮) |
226
- | action-left | 操作栏左侧附加区(与提交按钮同行靠左,如附件回形针) |
227
- | trigger | 指令弹框内容(作用域 { keyword }) |
228
-
229
- | Ref | 说明 |
230
- | --- | --- |
231
- | submit() / cancel() / clear() | 提交 / 停止 / 清空 |
232
- | focus(pos?) / blur() | pos: 'all' 全选 \| 'start' 头 \| 'end' 尾(缺省 end) |
233
- | openHeader() / closeHeader() | 显隐 #header 插槽 |
234
-
235
- ### MentionSender
236
-
237
- 带 @提及 的 Sender(键盘 ↑↓ 导航 / Enter 确认 / Esc 关闭)。
238
-
239
- | Prop | 类型 | 默认 | 说明 |
240
- | --- | --- | --- | --- |
241
- | modelValue | string(v-model) | '' | 输入值 |
242
- | userList | MentionUserInfo[] | [] | @ 触发的候选用户(id/name/avatar/pinyin) |
243
- | customTrigger | MentionCustomTrigger[] | [] | 自定义触发组 { dialogTitle, prefix, tagList } |
244
- | asyncMatchFun | (search) => Promise<MentionUserInfo[]> | — | 异步候选(存在时防抖 300ms,后端过滤) |
245
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(候选加载文案);内嵌 Sender 的文案经祖先注入(如 AiChat)或全局设置生效 |
246
-
247
- 事件:`update:modelValue` / `change` / `submit` / `cancel` / `trigger` / `recording-change` / `paste-file` / `update:triggerPopoverVisible` / `show-at-dialog`(弹层显隐);其余 props/事件经 `$attrs` 透传给 Sender,slot 经 forwardedSlots 显式转发(header/footer/prefix/action-list/trigger)。
248
-
249
- | Ref | 说明 |
250
- | --- | --- |
251
- | submit / cancel / clear / focus / blur / openHeader / closeHeader | Sender 方法转发 |
252
- | setUserTag(userId) | 光标处程序化插入 @用户 |
253
- | setCustomTag(prefix, id) | 光标处插入自定义触发标签 |
254
-
255
- ### EditorSender
256
-
257
- 富文本标签编辑器(contenteditable),open-webui 风格标签芯片。
258
-
259
- | Prop | 类型 | 默认 | 说明 |
260
- | --- | --- | --- | --- |
261
- | placeholder | string | '' | 占位文案 |
262
- | device | 'pc' \| 'h5' | 'pc' | 设备形态(仅影响样式) |
263
- | autoFocus | boolean | false | 挂载后聚焦到末尾 |
264
- | variant | 'default' \| 'updown' | 'default' | 布局形态 |
265
- | userList | EditorUser[] | [] | @ 候选用户 |
266
- | customTrigger | EditorCustomTrigger[] | [] | 自定义触发组 |
267
- | selectList | EditorSelectGroup[] | [] | 选择标签分组(openSelectDialog 弹窗数据) |
268
- | maxLength | number | 0 | 纯文本最大长度(0 不限;性能开销大,仅显式开启) |
269
- | submitType | 'enter' \| 'shiftEnter' | 'enter' | 提交按键模式 |
270
- | customStyle | Record<string, any> | {} | 根节点自定义样式 |
271
- | loading | boolean | false | 加载态(发送键变停止键) |
272
- | disabled | boolean | false | 禁用 |
273
- | clearable | boolean | false | 显示清空按钮 |
274
- | headerAnimationTimer | number | 300 | 头部过渡时长(ms) |
275
- | asyncMatchFun | (search) => Promise<EditorUser[]> | — | 异步 @ 候选(防抖 300ms) |
276
- | customDialog | boolean | false | 选择标签不自弹内置弹窗,仅上抛 show-select-dialog |
277
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
278
-
279
- | Event | 说明 |
280
- | --- | --- |
281
- | submit / change | (SubmitResult) SubmitResult = { text, html, tags: { userTags, selectTags, inputTags, customTags } } |
282
- | cancel | 点击停止按钮 |
283
- | show-at-dialog / show-select-dialog / show-tag-dialog | 各弹层显隐 |
284
-
285
- | Slot | 说明 |
286
- | --- | --- |
287
- | header / footer / prefix / action-list | 同 Sender |
288
- | tag-tip | 输入标签 tip 弹层内容(作用域 { nodeId }) |
289
-
290
- | Ref | 说明 |
291
- | --- | --- |
292
- | getCurrentValue() | 取 { text, html, tags } |
293
- | focusToStart() / focusToEnd() / blur() / selectAll() / clear() | 光标与清空 |
294
- | setText(text) / setHtml(html) / setMixTags(rows) | 程序化写入 |
295
- | setUserTag(id) / setCustomTag(prefix, id) / setInputTag(id, name) / setSelectTag(list) | 插入各类标签 |
296
- | customSetUser(user) / customSetTag(tag) | 外部直传对象插入(不经列表查表) |
297
- | updateSelectTag(method, options) | 选择标签更新:'insertTag'/'updateTagValue'/'deleteTag'/'updateTagStyle' |
298
- | openSelectDialog() / openTipTag(nodeId?) / closeTipTag() | 弹窗控制 |
299
- | openHeader() / closeHeader() | 显隐 #header |
300
- | chat / opNode(method, options) / chatState() | 底层文档模型:chat.insert/update/delete/append;opNode 按方法名分发 |
301
-
302
- ### Thinking
303
-
304
- 思考链折叠面板。
305
-
306
- | Prop | 类型 | 默认 | 说明 |
307
- | --- | --- | --- | --- |
308
- | modelValue | boolean(v-model) | false | 展开/收起 |
309
- | content | string | '' | 思考内容(常配合 #content 插槽嵌 FvMarkdown) |
310
- | status | 'start' \| 'thinking' \| 'end' \| 'interrupted' \| 'error' | 'start' | 思考状态(interrupted 为用户中断态,警告橙图标) |
311
- | disabled | boolean | false | 禁用切换 |
312
- | autoCollapse | boolean | false | status 变为 end 时自动收起 |
313
- | hideHeader | boolean | false | 隐藏折叠头(单 item 链平铺形态):不渲染切换按钮,内容区常驻展开 |
314
- | buttonWidth | string | '' | 切换按钮区宽度 |
315
- | maxWidth | string | '' | 内容区最大宽度 |
316
- | color / backgroundColor | string | '' | 前景色 / 背景色 |
317
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
318
-
319
- | Event | 说明 |
320
- | --- | --- |
321
- | update:modelValue | 展开/收起同步 |
322
-
323
- | Slot | 说明 |
324
- | --- | --- |
325
- | status-icon / label / arrow | 自定义状态图标 / 文案 / 箭头 |
326
- | content / error | 思考内容 / error 态内容 |
327
-
328
- | Ref | 说明 |
329
- | --- | --- |
330
- | modelValue / toggle() | 展开状态 / 手动切换 |
331
-
332
- ### ThoughtChain
333
-
334
- 思维链步骤条。text 步(kind: 'text')为「正在思考/思考完成」标题行 + 可折叠 description 滚动区(默认收起;展开时 ElScrollbar 限高 269px,流式期间自动滚底;内容被滚动裁掉的方向在上/下缘渲染 35px 渐隐条 `scroll-edge-fade-top` / `scroll-edge-fade-bottom`,贴顶/贴底各自隐藏);工具步 kind: 'tool' 为普通步骤行。
335
-
336
- | CSS 变量 | 默认 | 说明 |
337
- | --- | --- | --- |
338
- | --fv-chain-edge-fade-color | var(--el-bg-color) | text 步滚动区上/下缘渐隐条颜色(默认跟随页面底色,暗色模式经 element-plus 变量自动适配;思考链叠在非底色卡片上时可覆盖) |
339
-
340
- | Prop | 类型 | 默认 | 说明 |
341
- | --- | --- | --- | --- |
342
- | items | ThoughtChainItem[] | [] | 步骤项 { key, title?, status?: 'pending'/'success'/'loading'/'error', icon?, description?, kind?: 'tool'/'text', typing?, closed? } |
343
- | direction | 'vertical' \| 'horizontal' | 'vertical' | 排列方向 |
344
- | collapsible | boolean | false | 工具步长文案展开/收起(超 3 行截断 + 行尾「展开」) |
345
- | showDuration | boolean | false | 显示工具步用时 description(text 步 description 不受影响) |
346
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
347
-
348
- | Slot | 说明 |
349
- | --- | --- |
350
- | content | 覆盖默认 title/description(作用域 { item, index }) |
351
-
352
- ### Welcome
353
-
354
- 空态欢迎页。icon/name/description 均未传时显示内置品牌默认欢迎(「你好,我是 Gizmo」问候高亮 + IP 形象动图 + 默认描述),逐 prop 独立覆盖。
355
-
356
- 结构:图标区(DOM 序在前)+ 主列(`.fv-welcome-main`:文案列 + 建议区);纵排图标居中显示在文案上方;横排主列为唯一文档流内容(左对齐),吉祥物浮层悬于文案右上(经 flex order 排到主列右侧)——建议区与文案同列,不会把吉祥物顶高。
357
-
358
- | Prop | 类型 | 默认 | 说明 |
359
- | --- | --- | --- | --- |
360
- | icon | string \| Component | '' | 图标(字符串为图片地址;未传渲染内置品牌欢迎动图,横排/纵排同图,仅尺寸不同:横排大图 108px×scale1.8,纵排 96px) |
361
- | name | string | '' | 名称(未传回落内置问候语「你好,我是 Gizmo」) |
362
- | description | string | '' | 描述(纯文本;未传回落内置默认描述) |
363
- | layout | 'vertical' \| 'horizontal' | 'vertical' | 布局:vertical 纵排(吉祥物居中在文案上方)/ horizontal 横排(文案左对齐,欢迎吉祥物浮层悬于文案右上,空态欢迎形态,原型 .intro 同构) |
364
- | locale | LocaleInput | undefined | 语言包(内置欢迎文案) |
365
-
366
- | Slot | 说明 |
367
- | --- | --- |
368
- | icon / name / description | 覆盖对应区块 |
369
- | suggestions | 建议区(AiMessages 在此渲染 Prompts 快捷条;横排时与文案同列靠左) |
370
-
371
- ### CSS 变量
372
-
373
- | CSS 变量 | 默认 | 说明 |
374
- | --- | --- | --- |
375
- | --fv-welcome-icon-size | 纵排 96px | 内置品牌动图尺寸(纵排;横排吉祥物固定 108px×scale1.8 对齐原型) |
376
- | --fv-welcome-max-width | 780px | 空态欢迎块宽度(AiMessages 空态轴线;文案/吉祥物/快捷条共用。AiChat 整框内空态时与输入区同轴,回落 --fv-empty-max-width;独立使用 AiMessages 时为 780px,可覆盖) |
377
- | --fv-welcome-desc-max-width | 590px | 横排描述文字最大宽度(原型 .intro p) |
378
-
379
- ### Prompts
380
-
381
- 建议 prompt 网格。
382
-
383
- | Prop | 类型 | 默认 | 说明 |
384
- | --- | --- | --- | --- |
385
- | prompts | PromptItem[] | [] | 建议项 { key(必填), label?, description?, icon?(EP 图标名字符串或组件), disabled? } |
386
- | title | string | '' | 网格标题 |
387
- | wrap | boolean | true | 换行模式(默认 true 自动换行;false 不换行,超出部分横向滚动) |
388
-
389
- | Event | 说明 |
390
- | --- | --- |
391
- | select | (item) 点击(disabled 项不触发) |
392
-
393
- | Slot | 说明 |
394
- | --- | --- |
395
- | default | 覆盖整卡(作用域 { item, index }) |
396
-
397
- ### FilesCard
398
-
399
- 单个文件卡片。文档模式按扩展名自动映射**设计稿类型图标**(f-*.svg):xlsx/xls/csv 等表格→excel、pdf→pdf、pptx/ppt→ppt、docx/doc/wps→word、txt/md/json/log 等文本→txt,未命中回落通用 file 图标;图标 fill=currentColor 随主题色走。
400
-
401
- | Prop | 类型 | 默认 | 说明 |
402
- | --- | --- | --- | --- |
403
- | name | string | '' | 文件名 |
404
- | fileType | 'image' \| 'file' | 'file' | image 渲染缩略图,file 渲染类型图标卡 |
405
- | size | number \| string | 0 | 文件大小(字节自动格式化为 B/KB/MB;字符串原样展示;0 不显示) |
406
- | url | string | '' | 图片地址(image 模式缩略图) |
407
- | status | 'loading' \| 'success' \| 'error' | 'success' | loading:图标位换 spinner + 名称行下「上传中…」(卡内显示);error 红边 + 失败原因 |
408
- | errorText | string | '' | 失败原因红字(error 态展示于卡片下方,超宽截断 title 全文) |
409
- | imageSize | string | '' | 缩略图尺寸(width/height 同值) |
410
- | onDelete | () => void | — | 删除按钮回调(按钮常驻右上角,hover 浮现) |
411
- | onDownload | () => void | — | 下载回调:注入时右上角渲染下载按钮(28px hover 浮现,比删除按钮大一圈,垂直居中)。消息附件卡走此路(内置触发浏览器下载),输入区附件卡不注入 |
412
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
413
-
414
- | Slot | 说明 |
415
- | --- | --- |
416
- | image | 覆盖图片区(默认 url 缩略图,无 url 渲染 Picture 占位) |
417
-
418
- ### Attachments
419
-
420
- 附件选择与列表(v-model)。
421
-
422
- | Prop | 类型 | 默认 | 说明 |
423
- | --- | --- | --- | --- |
424
- | modelValue | object[](v-model) | [] | 附件列表(项含 uid/name/size/url/fileType/status/raw) |
425
- | accept | string | '' | input accept,如 'image/*' |
426
- | tip | string | '' | 内联提示文案 |
427
- | count | number | 0 | 最大附件数(超出走 @exceed;0 不限) |
428
- | beforeUpload | (file) => boolean \| Promise<boolean> | — | 上传前校验,返回 false 拦截 |
429
- | upload | (file, item) => Promise\<Partial\<AttachmentItem\> \| undefined \| void\> \| ... | — | 上传钩子(先传后发):选文件即调——入列即 loading,成功返回附件描述(含服务端附件 id)回填列表项置 success,失败(抛错/resolve 错误文案串)置 error 带失败原因(可重传再走钩子);缺省不调(纯本地待发列表,入列直接 success) |
430
- | disabled | boolean | false | 整体禁用(触发按钮不可点;生成中锁定输入场景,单飞行闸语义) |
431
- | layout | 'inline' \| 'triggerOnly' \| 'listOnly' | 'inline' | 布局:inline 回形针+列表+提示一行;triggerOnly 只渲染回形针按钮;listOnly 只渲染文件列表(拆分布局供整框组合:按钮进操作栏、列表进输入区上方) |
432
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
433
-
434
- | Event | 说明 |
435
- | --- | --- |
436
- | update:modelValue / change | 列表变化(全量数组) |
437
- | exceed | (file) 超出 count |
438
- | delete | (item) 删除某项 |
439
- | uploaded | (item, result?) 上传钩子落定(单项):成功回填后的列表项 + 上传结果;失败时 result 为 undefined(失败原因在 item.errMessage,FilesCard 红字展示) |
440
-
441
- | Slot | 说明 |
442
- | --- | --- |
443
- | list-item | 覆盖项渲染(作用域 { item, index }) |
444
- | list-thumb | 覆盖图片缩略图(作用域 { item, index }) |
445
-
446
- | Ref | 说明 |
447
- | --- | --- |
448
- | openSelect() | 程序化打开文件选择 |
449
- | retry(item) | error 项重新置为 loading(上传逻辑由外部接线) |
450
-
451
- ### Conversations
452
-
453
- 会话列表(按 group 分组)。
454
-
455
- | Prop | 类型 | 默认 | 说明 |
456
- | --- | --- | --- | --- |
457
- | items | ConversationItem[] | [] | 会话项 { key(必填), label(必填), group?, disabled? } |
458
- | active | string \| number(v-model:active) | undefined | 当前激活会话 key |
459
- | showBuiltInMenuType | 'hover' \| 'always' | 'hover' | 内置菜单按钮显隐方式 |
460
- | groupable | (a, b) => number | — | 分组排序比较器(缺省保持插入顺序) |
461
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
462
-
463
- | Event | 说明 |
464
- | --- | --- |
465
- | update:active / change | 选中会话(key / item) |
466
- | menu-command | ({ item, command: 'rename'/'delete', value? }) 菜单指令;rename 确认后带新名称 |
467
-
468
- | Slot | 说明 |
469
- | --- | --- |
470
- | group-title | 分组标题(作用域 { group }) |
471
- | item | 覆盖行内容(作用域 { item, active }) |
472
- | menu | 覆盖菜单项(默认重命名/删除;作用域 { item }) |
473
-
474
- | Ref | 说明 |
475
- | --- | --- |
476
- | handleMenuCommand({ item, command }) | 程序化触发菜单指令转发(纯转发,同步上抛 menu-command) |
477
- | renamePrompt(key) | 弹重命名输入框,确认后上抛 menu-command |
478
- | deleteConfirm(key) | 弹删除确认框,确认后上抛 menu-command |
479
-
480
- ## 对话应用层 API
481
-
482
- ### AiChat
483
-
484
- 对话整框:顶栏(标题+模型多选)、消息区(空态 Welcome/Prompts)、输入区(Sender)、可选 Artifacts 面板。
485
-
486
- | Prop | 类型 | 默认 | 说明 |
487
- | --- | --- | --- | --- |
488
- | model | string | '' | 默认模型(未传 models 时作为单模型) |
489
- | models | string[] | [] | 可选模型列表(有值时顶栏多选选择器) |
490
- | baseURL | string | '' | OpenAI 兼容服务地址(未传 adapter 时构造 OpenAIAdapter) |
491
- | apiKey | string | '' | 服务密钥 |
492
- | adapter | ChatAdapter | undefined | 聊天适配器(与 baseURL 二选一,优先) |
493
- | messages | MessageNode[](v-model:messages) | undefined | 消息链(半受控,见下) |
494
- | title | string | '' | 顶栏标题(同时作空态欢迎页名称;未传时欢迎页显示内置默认问候「你好,我是 Gizmo」) |
495
- | showHeader | boolean | false | 显示顶栏(标题 + 模型选择器;models 多选选择器在顶栏内,需开启才可见) |
496
- | centerWelcome | boolean | true | 空态居中:未开始对话时欢迎内容与输入区整体垂直居中,首条消息后输入区恢复固定底部 |
497
- | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(透传 AiMessages;距底超过 scrollButtonThreshold 时出现) |
498
- | scrollButtonThreshold | number | 100 | 滚到底部悬浮按钮显示阈值(px,透传 AiMessages) |
499
- | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px,透传 AiMessages):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动;调小可恢复更灵敏的跟随 |
500
- | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;false 时用户消息不渲染头像;助手头像不受影响) |
501
- | showUserName | boolean | false | 显示用户名称(默认隐藏;false 时用户消息不渲染头部名称行;助手名称不受影响) |
502
- | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像;用户头像不受影响) |
503
- | showAssistantName | boolean | false | 显示助手名称(默认隐藏;false 时助手消息不渲染头部名称行;用户名称不受影响) |
504
- | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标;`user-avatar` 插槽优先) |
505
- | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif;`assistant-avatar` 插槽优先) |
506
- | assistantAvatarScale | number | 1 | 助手头像缩放系数(默认 1 不缩放;亦可用 CSS 变量 --fv-msg-avatar-scale 覆盖,prop 优先) |
507
- | avatarCircle | boolean | true | 头像圆形模式(默认 true:圆角 50%;false 回落默认圆角;亦可用 CSS 变量 --fv-msg-avatar-radius 直接覆盖圆角取值,变量优先于开关) |
508
- | userName | string | '' | 用户名称(空串回落「你」;`user-name` 插槽优先) |
509
- | assistantName | string | '' | 助手名称(空串回落「Gizmo」;`assistant-name` 插槽优先) |
510
- | placeholder | string | '' | 输入框占位(缺省回落语言包 sender.inputPlaceholder:zh「输入你的问题,查询数据、分析问题或生成报表…」) |
511
- | senderAutosize | { minRows?; maxRows? } | { minRows: 3, maxRows: 7 } | 输入区自增高(透传 Sender autosize;默认 3 行起步,内容多时自动加高至最多 7 行后内部滚动) |
512
- | toolStepLabel | (toolName) => string | undefined | 工具名 → 步骤展示名(透传 useChat toolStepLabel) |
513
- | typing | boolean \| { step?; interval? } | false | 打字机(透传 AiMessages;仅 assistant 流式期间逐字平滑打出,落定/历史消息整段渲染) |
514
- | autoCollapse | boolean | true | 正文出完自动收起思考链(透传 AiMessage;status 落 done 且正文打完才收;error 不收) |
515
- | collapsible | boolean | false | 思考链工具步长文案展开/收起(透传 ThoughtChain;超 3 行截断 + 行尾「展开/收起」) |
516
- | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
517
- | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:`message.createdTime`——Fv 系后端直灌,秒级/毫秒级时间戳或 ISO 字符串自动识别——优先,缺省回落 `message.createdAt`。助手消息 SSE 生成中不显示,正文打完字(未启用打字机则落定)后才显示;error 即显;user 消息恒显示) |
518
- | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
519
- | senderShadow | boolean | true | 输入区阴影效果(透传 Sender 的 shadow) |
520
- | suggestions | AiChatSuggestion[] | [] | 空态建议列表(Prompts 项,key 必填;空态快捷条为胶囊形态,description 不显示) |
521
- | suggestionsWrap | boolean | true | 空态建议换行模式(true 自动换行;false 不换行,超出横向滚动) |
522
- | followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式(透传 AiMessages→AiMessage):'list' 纵向列表一行一条,渲染在回答操作区下方,顶部灰色分隔线 + **加粗**「追问」标题(字号/颜色随正文,标题文案经语言包 `aiMessage.followupsTitle` 自定义),条目 100% 宽、下划线分隔、字号随正文,历史消息同样渲染;'chips' 为旧横向气泡形态(换行铺排,无标题)。**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示,落定+打完字整体浮现) |
523
- | features | AiChatFeatures | {} | 特性开关 { artifacts?, tts?, queue?, continueGenerate?, fullscreenEditor? }(当前仅 artifacts 生效);artifacts 传 `true` 用默认配置,传对象 `{ width?, minWidth?, maxWidth?, autoOpen?, codeBlockTrigger? }` 自定义:宽度三参控面板尺寸(默认 420px/360px/60%),autoOpen(默认 true)检测到代码块自动弹面板,codeBlockTrigger(默认 true)在消息 html/svg 代码块右上角显示「预览」按钮、点击打开对应面板 |
524
- | allowAttachments | boolean | false | 开启输入区附件上传(回形针在操作栏左侧与提交按钮同行,已选列表在输入框上方;只传附件不输文字也可提交) |
525
- | accept | string | '' | 附件 input accept 属性(透传 Attachments),如 `image/*,.pdf,.txt`。缺省 '' 不限制(zip/exe 等是否可传由消费方自主决定);显式传值时除选择器过滤外组件内注入 beforeUpload 硬校验——白名单外文件(选择器切「所有文件」绕过 accept)不入列,自动 toast 提示(文案经语言包 `errors.attachmentRejected` 自定义,`{name}` 为文件名)并上抛 @attachment-reject |
526
- | attachmentLimit | number | 0 | 附件数量上限(0 不限,超限走 @attachment-exceed) |
527
- | uploadAttachment | (file, item) => Promise\<Partial\<AttachmentItem\> \| string \| undefined \| void\> \| ... | undefined | 附件上传钩子(先传后发):选文件即调,成功返回附件描述(id/name/type 等回填列表项,id 随发送进入 adapter 的 user 消息 files);返回错误文案串/抛错置 error 可重传。缺省不调(附件仅本地待发展示,不落服务端);上传中(loading 项)提交按钮禁用拒发,error 残留项不随发送 |
528
- | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(鉴权取流):消息气泡渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址)。远端 url 解析结果组件内按 url 缓存 + 在途去重;解析失败回落原 url 不阻塞渲染 |
529
- | feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessages→AiMessage;仅 assistant 最终回答行渲染 👍/👎,缺省不渲染按钮)。消费方在此接后端评价端点(如 Fv 系 POST /message/feedback):resolved 即成功;返回错误文案串/抛错触发 feedback-error(乐观更新已回滚);action=CLEAR 取消评价(comment 忽略)。交互语义:点击 👍 直接提交(不弹附言),点击 👎 弹**居中附言弹窗**(textarea ≤500 字 + 提交/跳过),再次点击当前态按钮发 CLEAR 取消评价(附言一并清空);👍↔👎 任意切换,后一次整体覆盖前一次(含附言);提交中按钮禁用防连点 |
530
- | theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题(向 html 注入/移除 dark class) |
531
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(解析后注入整框后代) |
532
-
533
- **v-model:messages 半受控语义**:外部 `messages` 仅在 setup 时一次性深拷贝灌入(用于恢复历史);组件内部每次变更全量上抛 `update:messages`(同帧去抖),父组件需经 v-model 回写维持单向数据流;父组件后续直接改 prop **不会**回灌生效。
534
-
535
- | Event | 说明 |
536
- | --- | --- |
537
- | update:messages | (MessageNode[]) 全量消息链(去抖后) |
538
- | send | (text, files?) 用户发送(allowAttachments 开启时 files 为降维后的 ChatFile[]) |
539
- | suggestion-select | (item) 点击空态建议项(先于 send 触发;label 为空的项不发) |
540
- | followup-select | (item, message) 点击回答尾部追问建议(先于 send 触发;组件内部已接住转 send 开启新一轮,事件仅供消费方可观测/埋点;assistant 消息带 suggestions 即渲染,不再限链尾——历史消息同样显示;正文打字效果完成后才渲染) |
541
- | message-complete | (message) 链尾 assistant 生成完成 |
542
- | error | (err, message?) 生成出错 |
543
- | branch-change | (dir, message) 分支切换 |
544
- | attachment-exceed | (file) 附件超过 attachmentLimit 上限 |
545
- | attachment-reject | (file) 附件被类型白名单拦截(显式 accept 的白名单外文件,如 zip/exe;文件选择器切「所有文件」绕过 accept 时由 beforeUpload 兜底拦截)。组件已自动 toast 提示,事件仅供消费方埋点/追加处理 |
546
- | attachment-uploaded | (item, { ok, message? }) 附件上传钩子落定(allowAttachments + uploadAttachment 场景):ok=false 时 message 为失败原因,宿主可 toast/埋点 |
547
- | message-file-click | (file, message) 点击消息气泡附件 chips:默认行为——图片类经 resolveFileUrl 解析后打开内置 ElImageViewer 放大(同消息多图轮播),文档类无内置行为,宿主接此事件自行下载 |
548
- | feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新),宿主可埋点/联动 |
549
- | feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
550
- | scroll | (event) 消息区滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
551
-
552
- | Slot | 说明 |
553
- | --- | --- |
554
- | message-avatar / message-actions | 透传给 AiMessages(作用域见 AiMessage;message-avatar 优先于细分头像插槽) |
555
- | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
556
- | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
557
- | welcome-name / welcome-description / welcome-icon | 单独配置欢迎页主标题/描述/吉祥物(转发 Welcome 同名插槽;优先于 title 等默认文案) |
558
- | welcome-suggestions | 单独配置欢迎页建议区(整体替换默认 Prompts 快捷条;建议渲染在文案下方与文案同列) |
559
- | empty | 覆盖空态整区 |
560
- | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
561
- | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
562
- | sender-prefix | 输入区前缀 |
563
-
564
- | CSS 变量 | 默认 | 说明 |
565
- | --- | --- | --- |
566
- | --fv-empty-max-width | 780px | 空态(welcome 态)轴线最大宽度:欢迎块/快捷条与输入区(Sender)共用同轴线,宽屏居中;仅空态生效,首条消息后恢复全宽 |
567
- | --fv-msg-avatar-size | 50px | 消息头像块边长(宽高同值;内置图标字号随块尺寸自适应) |
568
- | --fv-msg-avatar-radius | 50%(avatarCircle 默认开) | 消息头像圆角(avatarCircle=false 时回落默认圆角;直接赋值可自定义任意圆角,优先于开关) |
569
- | --fv-msg-avatar-scale | 1 | 助手头像缩放系数(默认 1 不缩放;放大可裁掉图片四周留白;assistantAvatarScale prop 优先于此变量) |
570
-
571
- | Ref | 说明 |
572
- | --- | --- |
573
- | sendMessage(text, files?) | 程序化发送 |
574
- | stop() | 停止生成(保留半截内容,静默收口不发 complete/error) |
575
- | regenerate(messageId?) | 重生成(缺省链尾 assistant) |
576
- | appendToMessage(id, text) | 向指定消息追加文本 |
577
- | clearMessages() | 清空消息树 |
578
- | exportTxt() | 导出当前链为纯文本 |
579
- | openArtifact(key) | 程序化打开某个 artifact |
580
- | expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链(user 消息、无思考链消息、单 item 平铺形态不受控) |
581
- | scrollTo(options) | 消息区滚动到指定位置(options 同原生 ScrollToOptions,如 { top: 0, behavior: 'smooth' };也可传 number) |
582
-
583
- ### AiMessages
584
-
585
- 消息列表(空态渲染 Welcome,建议快捷条经 Welcome #suggestions 插槽渲染在文案下方),吸底滚动。
586
-
587
- | Prop | 类型 | 默认 | 说明 |
588
- | --- | --- | --- | --- |
589
- | messages | MessageNode[] | —(必填) | 当前链消息(根 → 焦点) |
590
- | nodes | Record<string, MessageNode> | {} | 全量节点表(分支计算需查父 childrenIds) |
591
- | icon | string \| Component | '' | 空态欢迎页图标 |
592
- | name | string | '' | 空态欢迎页名称 |
593
- | description | string | '' | 空态欢迎页描述 |
594
- | suggestions | AiMessagesSuggestion[] | [] | 空态建议列表 |
595
- | suggestionsTitle | string | '' | 空态建议区标题 |
596
- | suggestionsWrap | boolean | true | 空态建议换行模式(true 自动换行;false 不换行,超出横向滚动) |
597
- | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动 |
598
- | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(空态不渲染) |
599
- | scrollButtonThreshold | number | 100 | 距底超过该值(px)才显示滚到底部悬浮按钮 |
600
- | showActions | boolean | true | 显示消息操作按钮(复制/重生成;生成中 pending/streaming 不渲染) |
601
- | showBranchSwitch | boolean | true | 显示分支切换器 |
602
- | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;助手头像不受影响) |
603
- | showUserName | boolean | false | 显示用户名称(默认隐藏;助手名称不受影响) |
604
- | showAssistantAvatar | boolean | true | 显示助手头像(用户头像不受影响) |
605
- | showAssistantName | boolean | false | 显示助手名称(默认隐藏;用户名称不受影响) |
606
- | userAvatar | string | '' | 用户头像图片 URL(透传 AiMessage) |
607
- | assistantAvatar | string | '' | 助手头像图片 URL(透传 AiMessage;传入完全覆盖不分状态,空串按状态回落内置 GIF) |
608
- | assistantAvatarScale | number | 1 | 助手头像缩放系数(透传 AiMessage;默认 1 不缩放) |
609
- | userName | string | '' | 用户名称(透传 AiMessage) |
610
- | assistantName | string | '' | 助手名称(透传 AiMessage;空串回落「Gizmo」) |
611
- | showTime | boolean | true | 显示消息时间(透传 AiMessage;时间源 createdTime 优先,缺省回落 createdAt。助手消息生成中不显示,打完字后才显示) |
612
- | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传 AiMessage) |
613
- | autoCollapse | boolean | true | 正文出完自动收起思考链(透传 AiMessage;status 落 done 且正文打完才收;error 不收) |
614
- | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(透传 AiMessage;鉴权取流换可直渲地址,见 AiChat) |
615
- | followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式(透传 AiMessage;默认 'list' 纵向列表——顶部灰色分隔线 + 加粗「追问」标题(字号/颜色随正文)、条目 100% 宽下划线分隔字号随正文;'chips' 旧横向气泡,见 AiChat)。**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示) |
616
- | feedbackHandler | (message, action, comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessage;语义见 AiChat,缺省不渲染 👍/👎) |
617
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
618
-
619
- | Event | 说明 |
620
- | --- | --- |
621
- | select / copy / regenerate / branch-change | 建议选中 / 复制 / 重生成 / 分支切换,载荷同 AiChat |
622
- | followup-select | (item, message) 点击追问建议 chip(透传 AiMessage,载荷同 AiChat) |
623
- | message-file-click | (file, message) 点击消息附件 chips(透传 AiMessage;图片类默认打开内置放大预览,文档类宿主自行下载) |
624
- | feedback-change / feedback-error | 评价提交成功(message, action)/ 失败(错误文案;透传 AiMessage,语义见 AiChat) |
625
- | scroll | (event) 滚动容器滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
626
-
627
- | Slot | 说明 |
628
- | --- | --- |
629
- | empty | 覆盖空态整区 |
630
- | welcome-name / welcome-description / welcome-icon | 单独配置欢迎页主标题/描述/吉祥物(转发 Welcome 同名插槽) |
631
- | welcome-suggestions | 单独配置欢迎页建议区(整体替换默认 Prompts 快捷条) |
632
- | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
633
- | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
634
- | message-avatar / message-actions | 透传给每条 AiMessage(message-avatar 优先于细分头像插槽) |
635
- | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
636
- | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
637
-
638
- | CSS 变量 | 默认 | 说明 |
639
- | --- | --- | --- |
640
- | --fv-messages-max-width | none | 滚动内容最大宽度;超出部分左右居中(内层 `.fv-messages-inner`,配合 `margin: 0 auto`) |
641
-
642
- | Ref | 说明 |
643
- | --- | --- |
644
- | scrollTo(options) | 滚动到指定位置(options 同原生 ScrollToOptions,也可传 number) |
645
- | scrollToBottom(smooth?) / scrollToTop() | 滚动控制 |
646
- | expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链 |
647
-
648
- ### AiMessage
649
-
650
- 单条消息(Markdown 正文 + 思考链折叠 + 附件 + 操作区)。
651
-
652
- | Prop | 类型 | 默认 | 说明 |
653
- | --- | --- | --- | --- |
654
- | message | MessageNode | —(必填) | 消息节点 |
655
- | branch | AiMessageBranchInfo | undefined | 分支元数据 { count, index };缺省视为单分支 |
656
- | isLast | boolean | false | 是否当前链最后一条消息(由 AiMessages 注入)。**追问建议已不再限链尾**(历史消息同样渲染),本 prop 仅作透传兼容保留,不参与任何显隐判定 |
657
- | showActions | boolean | true | 显示复制/重生成。assistant **待回答落定(status=done)才渲染**——生成中(pending/streaming)不出复制/重生成/评价等工具按钮;error 无正文也不出;user 仅有文案(content 非空)时才渲染复制按钮——纯附件无文字的消息复制的是一段空串,按钮无意义不出;分支切换器不受此门控 |
658
- | showBranchSwitch | boolean | true | 显示分支切换器(branch.count > 1 时) |
659
- | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;false 时用户消息不渲染头像块) |
660
- | showUserName | boolean | false | 显示用户名称(默认隐藏;false 时用户消息不渲染头部名称行) |
661
- | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像块) |
662
- | showAssistantName | boolean | false | 显示助手名称(默认隐藏;false 时助手消息不渲染头部名称行) |
663
- | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标) |
664
- | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif) |
665
- | assistantAvatarScale | number | 1 | 助手头像缩放系数(默认 1 不缩放;CSS 变量 --fv-msg-avatar-scale 同效,prop 优先) |
666
- | avatarCircle | boolean | true | 头像圆形模式(透传 AiMessage;默认 true:圆角 50%;--fv-msg-avatar-radius 变量优先于开关) |
667
- | userName | string | '' | 用户名称(空串回落「你」) |
668
- | assistantName | string | '' | 助手名称(空串回落「Gizmo」) |
669
- | autoCollapse | boolean | true | 正文出完自动收起思考链(status 落 done 且正文打字机不再打字时折叠;error 不收,保留链供排查;历史消息不受影响,仍默认收起) |
670
- | typing | boolean \| { step?; interval? } | false | 打字机(透传 Typewriter;仅 assistant 流式期间生效,落定/历史消息整段渲染) |
671
- | collapsible | boolean | false | 思考链工具步长文案展开/收起开关(透传 ThoughtChain) |
672
- | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
673
- | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:message.createdTime(秒级/毫秒级时间戳或 ISO 字符串自动识别)优先,缺省回落 message.createdAt;两者皆无则不渲染。助手消息 SSE 生成中不显示,正文打完字(未启用打字机则落定)后才显示;error 即显;user 消息恒显示) |
674
- | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
675
- | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(透传 Markdown/Typewriter;命中语言的代码块右上角注入按钮,点击行为由消费方事件委托实现) |
676
- | followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式:'list'(默认)纵向列表一行一条,渲染在操作区(工具栏)下方,顶部灰色分隔线 + **加粗**「追问」标题(字号/颜色随正文,经语言包 `aiMessage.followupsTitle` 自定义),条目 100% 宽、下划线分隔、字号随正文;'chips' 旧横向气泡形态(换行铺排,无标题)。assistant 消息带 suggestions 即渲染——历史消息同样显示,不再限链尾;**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示,落定+打完字整体浮现) |
677
- | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子:渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址),远端地址解析结果按 url 缓存 + 在途去重,失败回落原 url |
678
- | feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子:仅 assistant 最终回答行(role=assistant 且 status=done,error/中断/生成中不渲染)渲染 👍/👎,缺省不渲染按钮。点击 👍 直接提交,点击 👎 弹**居中附言弹窗**(ElDialog,textarea ≤500 字 + 提交/跳过,点遮罩/ESC 关闭草稿保留、再点 👎 复填),再次点击当前态按钮发 CLEAR;乐观更新——先翻转 message.feedback 再调钩子,失败回滚并经 feedback-error 上抛,成功经 feedback-change 上抛;返回 resolved 即成功,返回错误文案串/抛错均视为失败。**弹窗标题/占位可自定义**(语言包 `aiMessage.feedback.dislikeTitle`/`dislikePlaceholder`;标题 `{name}` 占位渲染时替换为 assistantName,空串回落 defaultAssistantName) |
679
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
680
-
681
- > 用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。
682
-
683
- | Event | 说明 |
684
- | --- | --- |
685
- | copy / regenerate / branch-change | (message) / (message) / (dir, message) |
686
- | followup-select | (item, message) 点击追问建议(item 为建议文本;assistant 消息带 suggestions 即渲染——历史消息同样显示,不限链尾;**正文打字效果完成后才渲染**,落定后可点;AiChat 内部已接住转 send,直接用 AiMessage 时的消费方需自行接管发送) |
687
- | file-click | (file, message) 点击附件:图片缩略图默认打开内置 ElImageViewer 放大(同消息多图轮播,url 经 resolveFileUrl 解析);文档附件渲染为 FilesCard 卡片(类型图标 + 名称/大小,复用输入区同款),卡片右上角 28px 下载按钮(hover 浮现)——点击内置触发浏览器下载(url 经 resolveFileUrl 解析),不触发本事件;点击卡片本体仅上抛本事件(无内置下载行为,宿主可埋点/接管) |
688
- | feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新,宿主可埋点/联动) |
689
- | feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
690
- | typing | 打字机输出中(流式期间节奏性触发) |
691
-
692
- | Slot | 说明 |
693
- | --- | --- |
694
- | message-avatar | 自定义头像(作用域 { message };优先于细分头像插槽,两条角色消息均生效) |
695
- | user-avatar | 自定义用户头像(无作用域;优先于 userAvatar props) |
696
- | assistant-avatar | 自定义助手头像(作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于 assistantAvatar props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
697
- | user-name | 自定义用户名称(作用域 { message };优先于 userName props) |
698
- | assistant-name | 自定义助手名称(作用域 { message };优先于 assistantName props) |
699
- | message-files | 自定义附件渲染(作用域 { message, files };默认:图片缩略图按钮(点击内置放大预览),文档 FilesCard 卡片(类型图标 + 名称/大小,复用输入区同款,卡片右上 28px 下载按钮 hover 浮现可下载);user 消息只传附件无文字时不渲染空正文气泡) |
700
- | message-actions | 自定义操作区(作用域 { message }) |
701
-
702
- | Ref | 说明 |
703
- | --- | --- |
704
- | message | 当前消息节点(computed) |
705
- | expandThoughtChain() / collapseThoughtChain() | 展开/折叠本条消息的思考链(user 消息、无思考链、单 item 平铺形态调用无效) |
706
-
707
- ### AiArtifacts
708
-
709
- Artifacts 预览面板(iframe 沙箱,从消息 ```html / ```svg 代码块提取)。
710
-
711
- | Prop | 类型 | 默认 | 说明 |
712
- | --- | --- | --- | --- |
713
- | artifacts | AiArtifactItem[] | [] | artifact 列表 { key(必填), type: 'html'/'svg', content, title? } |
714
- | activeKey | string | '' | 当前展示的 key;为空时面板隐藏 |
715
- | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
716
-
717
- | Event | 说明 |
718
- | --- | --- |
719
- | close / change | 关闭 / 切换(key) |
720
- | navigate | (href) iframe 内点击外链被拦截上抛 |
721
-
722
- | Ref | 说明 |
723
- | --- | --- |
724
- | open(key) / close() | 程序化显隐 |
725
-
726
- ## Composables
727
-
728
- ### useChat(options)
729
-
730
- 聊天编排:发送 → 流式回填 → 队列/重生成/续写。
731
-
732
- ```ts
733
- import { useChat, zhCN, en, ko, vi, zhHK } from '@fv-ui/ai-chat' // 内置语言包(可换成自建包)
734
-
735
- const lang = ref<'zh-CN' | 'en' | 'ko' | 'vi' | 'zh-HK'>('zh-CN')
736
-
737
- const LOCALES = { 'zh-CN': zhCN, en, ko, vi, 'zh-HK': zhHK }
738
-
739
- const chat = useChat({
740
- adapter: () => OpenAIAdapter({ baseURL, apiKey }), // 实例或工厂;工厂每次 send 惰性取用
741
- models: () => selectedModels.value, // 数组或工厂;多模型并行生成兄弟分支
742
- initial: { messages, currentId }, // 恢复会话
743
- onToolEvent: (ev) => { /* Fv 系通用 tool{status},展示「正在查询库存…」*/ },
744
- // 语言包工厂:返回 LocaleMessages 包对象(内置包或自建包),非语言名字符串
745
- locale: () => LOCALES[lang.value]
746
- })
747
- // chat: { send, stop, regenerate, continueGenerate, enqueue, queue, isLoading,
748
- // msgs, messages, currentId, chain }
749
- ```
750
-
751
- - `send(text, files?)`:生成中调用被拒;多模型时各模型一个 assistant 节点并发回填
752
- - `stop()`:中止全部在途请求,在途节点置 done(保留半截内容)
753
- - `regenerate(messageId?)`:回退焦点到父节点重发生成新分支(旧回答保留)
754
- - `continueGenerate(messageId?)`:以既有内容为前缀续写,增量追加到同一节点
755
- - `enqueue(text, files?)`:生成中入队,完成后自动 flush 队首
756
- - `onToolEvent`:适配器 `onTool` 回调的透传挂点(如 FvCommonAdapter 的 tool{status} 事件)
757
- - `locale`:语言包工厂 `() => LocaleMessages`,惰性取用(与 adapter/models 工厂同语义);影响附件 system prompt、工具用时、续写 prompt 等发给后端的文案,缺省读全局设置,见[国际化](#国际化i18n)
758
-
759
- ### FvCommonAdapter(config)
760
-
761
- Fv 系后端通用聊天适配器(`/api/ai-chat/*`):六事件 SSE 协议(`message_start` / `tool` / `delta` / `reasoning` / `message_end` / `error`),POST `/ai-chat/message/send`。适用于 Fv 各项目组返回此结构的后端。会话管理(列表/归档/删除等)由消费方直接调后端,不经此适配器。
762
-
763
- ```ts
764
- const adapter = FvCommonAdapter({
765
- baseURL: '/api', // 或 https://host
766
- headers: () => ({ Authorization: 'Bearer ' + token }), // 惰性取用
767
- sessionId: () => currentSessionId.value, // 工厂:切换会话后下一次 send 生效
768
- errorMessages: { 90602: '已有进行中的对话' } // 业务码 → 文案映射(可选)
769
- })
770
- ```
771
-
772
- - 同步段失败(Content-Type 非 `text/event-stream`)按 JSON 错误 `{code,message}` 走 `onError`;命中 `errorMessages` 时用映射文案(带 `code` 的 `FvCommonError`)
773
- - `message_end` 的 `messageId`(最终文本行 id)经 `onBackendMessageId` 回填到 `MessageNode.backendId`——多轮工具循环下与 `message_start` 的首轮 id 不同,UI 落库/对账以它为准
774
- - `tool` 事件经 `onTool` → `useChat.onToolEvent` → `AiChat @tool-event` 上抛,消费方展示「正在查询库存…」等中间态
775
- - 追问建议(V58+):`suggestions` 事件(流式收尾 0..1 次,最后一个 delta 后、message_end 前,载荷 `{items: string[]}`)经可选 `onSuggestions` 上抛,`useChat` 回写 `MessageNode.suggestions`,AiMessage 对带 suggestions 的 assistant 消息渲染追问(默认纵向列表样式——顶部灰色分隔线 + 加粗「追问」标题、条目 100% 宽下划线分隔字号随正文,`followupStyle='chips'` 切回横向气泡;**正文打字效果完成后才渲染**,流式事件到达不显示,历史消息同样渲染,不再限链尾);开关关闭/模型未产出/中断/失败无此事件;历史恢复用导出的 `parseSuggestions(raw)` 安全解析 `FvCommonMessage.suggestions`(JSON 数组原文透传,脏数据按无建议)
776
- - 消息评价(V58+):`FvCommonMessage.feedback`(LIKE/DISLIKE,未评价/旧数据恒 null)、`feedbackComment`(附言 ≤500 字)、`feedbackTime`(评价落库时间)三字段同款容错;历史恢复由消费方映射为 `MessageNode.feedback` 灌入展示;评价提交走独立端点(POST /message/feedback),不经本适配器——接 `AiChat` 的 `feedbackHandler` 钩子即可
777
- - 附件快照(1.4.1+):user 行 `FvCommonMessage.attachments`(id/originalName/type/suffix/sizeBytes/downloadUrl,旧数据/无附件恒 null),历史回放映射 `MessageNode.files` 渲染(图片缩略图 + 文档 FilesCard 卡片,卡片右上 28px 下载按钮 hover 浮现可下载;downloadUrl 需鉴权取流时配 `resolveFileUrl` 钩子,下载/预览均走解析后地址)
778
- - 配套 DTO 类型:`FvCommonSessionItem` / `FvCommonMessage` / `FvCommonSessionDetail` / `FvCommonMessagePage`(消费方直接调会话管理端点时用)
779
-
780
- ### useMessages(initial?)
781
-
782
- 树形消息状态中枢(响应式包装 `createMessageTree`)。
783
-
784
- 返回:`messages`(全量节点表)、`currentId`、`chain`(当前链 computed)、`add`、`remove`、`edit`、`appendContent`、`navigate(id?, dir?)`、`setCurrent(id)`、`setStorage(adapter)`、`load()`、`flush()`、`toJSON()`。绑定存储后树变更自动去抖(150ms)落盘。
785
-
786
- ### useXStream()
787
-
788
- SSE 流消费:`startStream({ readableStream, transformStream? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading`。内部完成 `\r\n`/跨 chunk 边界归一化。
789
-
790
- ### useSend() / XRequest
791
-
792
- `useSend()`:`send({ url, method?, headers?, body?, transformStream?, onChunk? })`(SSE data 为 JSON 且含 content 字段时逐块回调)、`abort()`、`loading`、`error`。在飞行守卫:上一个 send 未结束时新 send 被忽略。
793
-
794
- `XRequest(url, options)`:Promise 化,resolve 累计全文。
795
-
796
- ### useRecord()
797
-
798
- 语音录制 + 实时转写:`start()` / `stop()` / `isRecording` / `text` / `audioUrl` / `error`。SpeechRecognition 不可用时降级为仅录音。
799
-
800
- ## 自定义 ChatAdapter
801
-
802
- 实现 `ChatAdapter` 接口即可接入任意后端(自研网关、Ollama、非 OpenAI 协议):
803
-
804
- ```ts
805
- import type { ChatAdapter } from '@fv-ui/ai-chat'
806
-
807
- const myAdapter: ChatAdapter = {
808
- async send(req, handlers) {
809
- // req: { messages: [{ role, content }], model?, stream?, signal? }
810
- try {
811
- const res = await fetch('/api/chat', {
812
- method: 'POST',
813
- headers: { 'content-type': 'application/json' },
814
- body: JSON.stringify(req),
815
- signal: req.signal
816
- })
817
- if (!res.ok) { handlers.onError(new Error(`HTTP ${res.status}`)); return }
818
- // 流式:自行逐块解析,回调增量
819
- handlers.onDelta('一段正文')
820
- handlers.onReasoning('一段思考链') // 可选
821
- handlers.onUsage({ prompt_tokens: 10, completion_tokens: 20 }) // 可选
822
- handlers.onDone() // 正常结束必须调用
823
- } catch (e) {
824
- if (req.signal?.aborted) return // 主动中止不算错误
825
- handlers.onError(e instanceof Error ? e : new Error(String(e)))
826
- }
827
- },
828
- abort() {
829
- // 中止全部在途请求
830
- }
831
- }
832
-
833
- // 用法
834
- <FvAiChat title="AI" :adapter="myAdapter" />
835
- ```
836
-
837
- 一次 `send` 对应一次完整生成:持续回调 `onDelta` 增量,最后必须 `onDone()` 或 `onError()`;`stop()` 时组件会调 `abort()`。
838
-
839
- 持久化可选 `StorageAdapter`(`get/set/remove`,async),内置 `createLocalStorageAdapter()`(localStorage 不可用时自动降级内存)与 `createMemoryAdapter()`;经 `useMessages().setStorage()` 绑定。
840
-
841
- ## 主题定制
842
-
843
- 组件样式基于 Element Plus CSS 变量,覆盖 EP 变量即完成主题定制:
844
-
845
- ```scss
846
- // 全局或局部覆盖(需在引入 dist/style.css 之后)
847
- :root {
848
- --el-color-primary: #7c3aed;
849
- }
850
- ```
851
-
852
- 高级定制可直接 `@use` 源 SCSS 入口:
853
-
854
- ```scss
855
- @use '@fv-ui/ai-chat/src/styles/index.scss' with (
856
- // scss 变量(若组件有定义)
857
- );
858
- ```
859
-
860
- > 源码 SCSS 入口仅供源码依赖场景;npm 消费方推荐使用构建产物 `dist/style.css` + CSS 变量覆盖。
861
-
862
- ## 国际化(i18n)
863
-
864
- 内置五份语言包:`zh-CN`(默认,零配置)、`en`、`ko`、`vi`、`zh-HK`;所有组件文案(按钮 aria/tooltip、状态文案、MessageBox、错误提示、发给模型的续写 prompt)均从语言包读取。
865
-
866
- ### 全局设置(推荐)
867
-
868
- ```ts
869
- import { configureLocale } from '@fv-ui/ai-chat'
870
-
871
- configureLocale('en') // 整库切英文;configureLocale('zh-CN') 切回,可选 'ko'/'vi'/'zh-HK'
872
- ```
873
-
874
- ### 组件级 prop
875
-
876
- 每个含文案的组件都有 `locale` prop,两种形态:
877
-
878
- ```vue
879
- <!-- 整包切换(优先级最高) -->
880
- <FvAiChat locale="en" ... />
881
-
882
- <!-- 部分覆盖:在当前生效语言上深合并,只改指定文案 -->
883
- <FvAiChat :locale="{ aiMessage: { regenerate: '重答' }, sender: { send: 'GO' } }" ... />
884
- ```
885
-
886
- 解析优先级:**组件 prop > 祖先 `<FvAiChat>` 注入 > 全局设置**。`<FvAiChat>` 会把解析结果注入整框后代(Sender/消息区/Artifacts 等),后代组件的 `locale` prop 仍可局部覆盖;单独使用基础组件(FvSender/FvConversations...)时 prop 缺省则读全局。
887
-
888
- ### 自建完整语言包
889
-
890
- ```ts
891
- import { configureLocale, zhCN, type LocaleMessages } from '@fv-ui/ai-chat'
892
-
893
- const jaJP: LocaleMessages = {
894
- ...zhCN,
895
- common: { ...zhCN.common, send: '送信', copy: 'コピー' },
896
- aiMessage: { ...zhCN.aiMessage, defaultAssistantName: 'アシスタント' }
897
- // 未覆盖的 key 自动回落 zh-CN 值;建议展开全部 key 覆盖
898
- }
899
- configureLocale(jaJP)
900
- ```
901
-
902
- `configureLocale` 的对象形态是**完整语言包**(定基准);组件 `locale` prop 的对象形态是**部分覆盖**(在基准上微调),两者语义有意不同。
903
-
904
- ### 语言包 key 一览
905
-
906
- 下表列出 zh-CN 与 en 两列对照;`ko`/`vi`/`zh-HK` 词条与之一一同构,详见语言包源文件 `src/locale/{ko,vi,zh-HK}.ts`。
907
-
908
- | 分组 | key | zh-CN | en |
909
- | --- | --- | --- | --- |
910
- | common | copy / delete / confirm / cancel / retry / close / preview / clear / stop / send / download / fullscreen / collapse / expand | 复制 / 删除 / 确定 / 取消 / 重传 / 关闭 / 预览 / 清空 / 停止 / 发送 / 下载 / 全屏 / 收起 / 展开 | Copy / Delete / OK / Cancel / Retry / Close / Preview / Clear / Stop / Send / Download / Fullscreen / Collapse / Expand |
911
- | thinking | start / thinking / end / interrupted / error / endWithTools / interruptedWithTools / thinkingItem / thoughtDoneItem | 开始思考 / 思考中... / 思考完成 / 思考中断 / 思考遇到问题 / 思考完成,使用 {n} 个工具 / 思考中断,使用 {n} 个工具 / 正在思考 / 思考完成 | Thinking / Thinking... / Thought complete / Thought interrupted / Something went wrong / Thought complete, used {n} tools / Thought interrupted, used {n} tools / Thinking / Thought complete |
912
- | welcome | greetingPrefix / greetingName / description | 你好,我是 ␣ / Gizmo / 我可以帮你查询数据、分析问题、生成报表、以及执行系统操作,让生产管理更高效。 | Hello, I am ␣ / Gizmo / I can help you query data, analyze problems, generate reports, and perform system operations... |
913
- | sender | clear / stop / send / speech / recordCancel / recordConfirm / micUnavailable / inputPlaceholder | 清空 / 停止 / 发送 / 语音输入 / 取消录音 / 确认录音 / 无法访问麦克风 / 输入你的问题,查询数据、分析问题或生成报表… | Clear / Stop / Send / Voice input / Cancel recording / Confirm recording / Microphone unavailable / Ask a question — query data, analyze problems, or generate reports… |
914
- | editorSender | clear / stop / send / inputPlaceholder / selectTagTitle / loading / tagTip | 清空 / 停止 / 发送 / 请输入 / 选择标签 / 加载中… / 填写内容后回车确认 | Clear / Stop / Send / Type something... / Select a tag / Loading... / Type and press Enter to confirm |
915
- | attachments | add / retry / uploading | 添加附件 / 重传 / 上传中… | Add attachment / Retry / Uploading… |
916
- | filesCard | remove | 删除 | Remove |
917
- | conversations | menuLabel / rename / delete / renameTitle / renamePrompt / renamePlaceholder / deleteTitle / deleteConfirm | 会话操作 / 重命名 / 删除 / 重命名会话 / 请输入新的会话名称 / 请输入名称 / 删除会话 / 确定删除会话「{label}」吗?... | Conversation actions / Rename / Delete / Rename conversation / Enter a new conversation name / Enter a name / Delete conversation / Delete "{label}"? ... |
918
- | scroll | toBottom | 滚动到底部 | Scroll to bottom |
919
- | aiChat | modelPlaceholder / adapterMissing / generateFailed / exportUser / exportAssistant | 模型 / 未配置 adapter 或 baseURL / 生成失败 / 你 / 助手 | Model / Neither adapter nor baseURL is configured / Generation failed / You / Assistant |
920
- | aiMessage | copy / regenerate / prevBranch / nextBranch / defaultUserName / defaultAssistantName / querying / queried / generateFailed / followups / followupsTitle / loadingPhrases / feedback.{like, dislike, dislikeTitle, dislikePlaceholder, submit, skip, failed, cleared} | 复制 / 重新生成 / 上一分支 / 下一分支 / 你 / Gizmo / 正在查询 / 已查询 / 生成失败 / 追问建议 / 追问 / [正在思考…, 正在整理思路…, 正在生成回答…] / 点赞 / 点踩 / 抱歉,请告诉 {name} 哪里不好 / 欢迎说说你的想法 / 提交 / 跳过 / 评价提交失败 / 已取消评价 | Copy / Regenerate / Previous branch / Next branch / You / Gizmo / Querying / Queried / Generation failed / Follow-up suggestions / Follow-ups / [Thinking..., Organizing thoughts..., Generating your answer...] / Like / Dislike / Sorry — tell {name} what went wrong / Feel free to share your thoughts / Submit / Skip / Failed to submit feedback / Feedback removed |
921
- | aiArtifacts | copy / download / fullscreen / close | 复制 / 下载 / 全屏 / 关闭 | Copy / Download / Fullscreen / Close |
922
- | chat | fileTag / fileImageTag / filesSystemPrompt / toolDuration / continuePrompt | [附件] {name} / (图片) / 用户随消息提供了以下文件:\n{files} / 用时 {s} / 请基于以上内容继续完成回答... | [File] {name} / ␣(image) / The user provided... / Took {s} / Continue completing... |
923
- | errors | requestFailed / sessionIdMissing / noBody / generateFailed / recordUnsupported / speechError / attachmentRejected | 请求失败 / 缺少 sessionId(...) / 响应无 body / 生成失败 / 当前环境不支持音频录制 / 语音识别错误: {error} / 不支持该类型文件,禁止上传:{name} | Request failed / sessionId is missing... / Response has no body / Generation failed / Audio recording... / Speech recognition error: {error} / This file type is not supported: {name} |
924
-
925
- 占位符 `{label}`/`{name}`/`{files}`/`{s}`/`{n}`/`{error}` 由组件在渲染/构造时替换。`querying`/`queried` 与工具名拼接时由组件显式补一个空格(显示为「正在查询 xxx」),词条本身不含尾随空格,覆盖时无需保留间距。`welcome.greetingPrefix` 保留尾随空格(与 greetingName 直接拼接,高亮 span 交界处)。`aiMessage.loadingPhrases` 为生成中占位的轮换文案数组(进入占位立即显示第一条,此后每 3s 轮换循环);覆盖时数组**整体替换**(deepMerge 不合并数组叶子),传空数组则只显示 spinner 无文案。`aiMessage.feedback.dislikeTitle` 中的 `{name}` 由组件渲染点踩附言弹窗时替换为 `assistantName`(空串回落 `defaultAssistantName`),如需静态标题请直接传完整文案。
926
-
927
- ### 与 vue-i18n 共存
928
-
929
- 本库不依赖 vue-i18n。若项目已在用,把 LocaleMessages 挂进 vue-i18n messages 后引用其值传 prop 即可桥接:
930
-
931
- ```vue
932
- <FvAiChat :locale="$tm('fvAiChat')" /> <!-- $tm 返回 fvAiChat 节点的对象作为语言包传入 -->
933
- ```
934
-
935
- ### 已落库数据不回溯
936
-
937
- 语言切换只影响之后的渲染与请求;已写入消息树的工具用时(`用时 1.2s`)、历史 error 文案保持产生时的语言。
938
-
939
- ## 暗色模式
940
-
941
- `<FvAiChat theme="dark">` 或 `theme="auto"`(跟随 `prefers-color-scheme`):组件向 `<html>` 注入/移除 `dark` class,配合 element-plus 的暗色变量生效:
942
-
943
- ```ts
944
- // main.ts 引入 EP 暗色变量
945
- import 'element-plus/theme-chalk/dark/css-vars.css'
946
- ```
947
-
948
- ```vue
949
- <FvAiChat theme="auto" ... />
950
- ```
951
-
952
- 注意:组件卸载时会移除 `html.dark`(单实例假设);多实例并用暗色需自行管理 class。
953
-
954
- ## Prism 主题引入
955
-
956
- 代码高亮默认配色由组件样式提供;要换成其他 Prism 主题,在 `dist/style.css` 之后引入覆盖:
957
-
958
- ```ts
959
- import '@fv-ui/ai-chat/dist/style.css'
960
- import '@fv-ui/ai-chat/styles/prism-tomorrow.min.css'
961
- ```
962
-
963
- 内置主题:`prism`(默认)、`prism-coy`、`prism-dark`、`prism-funky`、`prism-okaidia`、`prism-solarizedlight`、`prism-tomorrow`、`prism-twilight`。
964
-
965
- ## FAQ
966
-
967
- **Q:页面是白屏/样式错乱?**
968
- A:确认已引入 `element-plus/dist/index.css` 与 `@fv-ui/ai-chat/dist/style.css`,且 `app.use(ElementPlus)`。
969
-
970
- **Q:`<FvAiChat>` 发送报"未配置 adapter 或 baseURL"?**
971
- A:`adapter` 与 `baseURL` 至少传一个。
972
-
973
- **Q:外层改了 `v-model:messages` 为什么界面没变?**
974
- A:半受控语义:外部 messages 只在初始灌入一次,后续界面变化全量上抛 `update:messages`,请经 v-model 回写而不是直接改源数组。
975
-
976
- **Q:多模型怎么用?**
977
- A:`<FvAiChat model="a" :models="['a', 'b']">` 顶栏出现多选,选中的多个模型并行生成,回答互为分支可切换。
978
-
979
- **Q:`features` 里的 tts/queue/continueGenerate/fullscreenEditor?**
980
- A:接口已预留,当前版本仅 `artifacts` 生效,其余待后续版本接线。
981
-
982
- **Q:KaTeX 公式没渲染?**
983
- A:FvMarkdown 内置 `@vscode/markdown-it-katex`,确认公式语法正确即可;无需额外引入。
984
-
985
- **Q:Vite dev 下内置头像/欢迎页 GIF 不显示(404 破图)?**
986
- A:Vite dev 的依赖预打包(esbuild)不复制 `new URL(..., import.meta.url)` 引用的资产(vitejs/vite#8427)。在 `vite.config.ts` 加 `optimizeDeps: { exclude: ['@fv-ui/ai-chat'] }`,详见[「Vite 项目必读」](#vite-项目必读排除依赖预打包)。
987
-
988
- **Q:Nuxt/SSR 环境首渲染报错 "DOMPurify 不可用:当前环境无 window"?**
989
- A:FvMarkdown 依赖浏览器 `window`(DOMPurify 消毒),不支持服务端首渲染。Nuxt 下请用 `<ClientOnly>` 包裹(或客户端挂载后再渲染):
990
-
991
- ```vue
992
- <ClientOnly>
993
- <FvAiChat ... />
994
- </ClientOnly>
995
- ```
996
-
997
- ## 已知限制与 Roadmap
998
-
999
- 以下能力数据层已就绪,组合 UI 待后续版本接线(v0.2 计划):
1000
-
1001
- - **消息列表懒加载**:`useMessages` 数据面支持分页注入,`AiMessages` 暂全量渲染;超长对话建议自行分页。
1002
- - **消息操作条**:当前内置复制/重新生成;编辑/删除/继续生成/朗读请经 `useChat`(`editMessage`/`removeMessage`/`continueGenerate`)或 `#message-actions` 插槽自建入口。
1003
- - **队列卡片**:`useChat.enqueue` 可用,`features.queue` 展示 UI 待接线。
1004
- - **语音输入**:`Sender` 的 `allowSpeech` 依赖浏览器 `SpeechRecognition`(Chrome/Edge 可用,Firefox 不支持转写,降级为仅录音、确认后无文本);录音/波形需要 HTTPS 或 localhost 环境。
1005
- - **多实例暗色互斥**:`theme` 采用单写者假设,多实例同屏请自行管理 `html.dark`。
1006
-
1007
- ## 类型与导出
1008
-
1009
- 包入口导出全部组件、`useChat`/`useMessages`/`useXStream`/`useSend`/`XRequest`/`useRecord`、`OpenAIAdapter`、`FvCommonAdapter`(+ `FvCommonError` 及配套 DTO 类型)、`parseSuggestions`(追问建议 JSON 安全解析)、`createMessageTree`、`createLocalStorageAdapter`/`createMemoryAdapter`、`createSSEParser`、`configureLocale`/`zhCN`/`en`/`ko`/`vi`/`zhHK`(国际化)及全部公共类型(`MessageNode`、`ChatAdapter`、`ChatFile`、`MessageFeedback`、`FeedbackHandler`、`MessageUsage`、`SSEEvent`、`LocaleMessages`、`LocaleCode`、`LocaleInput`、`DeepPartialLocale` 等),消费方:
1010
-
1011
- ```ts
1012
- import { FvAiChat, OpenAIAdapter, useChat } from '@fv-ui/ai-chat'
1013
- import type { MessageNode, ChatAdapter } from '@fv-ui/ai-chat'
1014
- ```
1
+ # @fv-ui/ai-chat
2
+
3
+ ![version](https://img.shields.io/badge/version-1.0.0-blue)
4
+ ![vue](https://img.shields.io/badge/vue-%5E3.4.0-brightgreen)
5
+ ![element-plus](https://img.shields.io/badge/element--plus-%5E2.7.0-blue)
6
+
7
+ 基于 Vue 3 + Element Plus 的 AI 对话组件库,复刻 element-plus-x 与 open-webui 对话框:从底层气泡、发送框、Markdown 渲染,到上层的对话整框(`<FvAiChat>`)、分支树消息、Artifacts 预览,一次给全。
8
+
9
+ - 14 个基础组件(Bubble/Sender/Markdown/Thinking/...)自由拼装
10
+ - 对话应用层整框 `<FvAiChat>`:顶栏模型多选、消息列表、分支切换、Artifacts 面板、发送停止一体化
11
+ - 树形消息模型(同构 open-webui):一条提问可挂多个模型回答,分支可切换、可重生成
12
+ - `ChatAdapter` 适配器协议:内置 OpenAI 兼容实现,可替换自研后端/Ollama
13
+ - 流式打字机、思考链折叠、KaTeX/代码高亮(Prism)开箱即用
14
+
15
+ ## 安装
16
+
17
+ ```bash
18
+ pnpm add @fv-ui/ai-chat
19
+ ```
20
+
21
+ peerDependencies:`vue ^3.4.0`、`element-plus ^2.7.0`、`@element-plus/icons-vue ^2.3.0`。
22
+
23
+ ## 快速开始
24
+
25
+ ```ts
26
+ // main.ts —— 需要先引入 element-plus(组件库依赖其组件与暗色变量)
27
+ import ElementPlus from 'element-plus'
28
+ import 'element-plus/dist/index.css'
29
+ import { createApp } from 'vue'
30
+ import App from './App.vue'
31
+
32
+ createApp(App).use(ElementPlus).mount('#app')
33
+ ```
34
+
35
+ ```vue
36
+ <!-- App.vue -->
37
+ <script setup lang="ts">
38
+ import { FvAiChat } from '@fv-ui/ai-chat'
39
+ import '@fv-ui/ai-chat/dist/style.css'
40
+ </script>
41
+
42
+ <template>
43
+ <FvAiChat
44
+ title="AI 助手"
45
+ base-url="https://api.deepseek.com/v1"
46
+ api-key="sk-xxx"
47
+ model="deepseek-chat"
48
+ style="height: 600px"
49
+ />
50
+ </template>
51
+ ```
52
+
53
+ `<FvAiChat>` 未传 `adapter` 时,用 `baseURL`/`apiKey`/`model` 构造内置 `OpenAIAdapter`(走 `/chat/completions`,SSE 流式)。两个都缺省时发送会报"未配置 adapter 或 baseURL"。
54
+
55
+ ### Vite 项目必读:排除依赖预打包
56
+
57
+ 内置头像/欢迎页 GIF 在 es 产物中以 `new URL(..., import.meta.url)` 按需引用。Vite dev server 默认把依赖交给 esbuild 预打包(optimizeDeps),而预打包**不会复制**该类资产——GIF 404 不显示(已知限制 [vitejs/vite#8427](https://github.com/vitejs/vite/issues/8427))。需在 `vite.config.ts` 排除预打包,让本包走源码 ESM 管线:
58
+
59
+ ```ts
60
+ // vite.config.ts
61
+ export default defineConfig({
62
+ optimizeDeps: {
63
+ // @fv-ui/ai-chat:es 产物内置 GIF 以 new URL(..., import.meta.url) 引用,
64
+ // esbuild 预打包不复制该类资产(vitejs/vite#8427),须排除预打包走源码 ESM 管线
65
+ exclude: ['@fv-ui/ai-chat']
66
+ }
67
+ })
68
+ ```
69
+
70
+ 说明:仅 Vite **dev** 需要;生产 `build` 走 Rollup 管线会自动把 GIF 复制进产物并重写路径,不受影响。UMD(`<script>` 直用 `lib/index.js`)不涉及。
71
+
72
+ ## 基础组件层 API
73
+
74
+ ### FvMarkdown
75
+
76
+ Markdown 渲染(Sanitized by DOMPurify),内置 Prism 代码高亮与 KaTeX。
77
+
78
+ | Prop | 类型 | 默认 | 说明 |
79
+ | --- | --- | --- | --- |
80
+ | content | string | (必填) | Markdown 源文本 |
81
+ | mdPlugins | PluginWithParams[] | | 额外 markdown-it 插件 |
82
+ | highlight | (str, lang) => string | 内置 Prism | 自定义代码高亮 |
83
+ | isTyping | boolean | | 打字机模式样式钩子(透传占位) |
84
+ | codeTriggerLangs | string[] | | 代码块「预览」触发语言(fence 原始 lang 命中列表时注入预览按钮,点击行为由消费方事件委托实现) |
85
+ | tableToolbar | boolean | true | 表格工具栏:表格上方注入复制(复制表格 markdown 源文本)/下载(导出 CSV,带 BOM)单图标按钮 |
86
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
87
+
88
+ | Ref | 说明 |
89
+ | --- | --- |
90
+ | getHtml() | 取当前渲染后的 HTML 字符串 |
91
+
92
+ ### Typewriter
93
+
94
+ 打字机输出,支持续打/重打/雾化遮罩。
95
+
96
+ | Prop | 类型 | 默认 | 说明 |
97
+ | --- | --- | --- | --- |
98
+ | content | string | (必填) | 全文(流式时增量传入,子集扩展自动续打) |
99
+ | isMarkdown | boolean | false | 走 FvMarkdown 渲染(此时 suffix 不追加) |
100
+ | isFog | boolean \| { bgColor?; width? } | false | 打字中尾部雾化遮罩 |
101
+ | typing | boolean \| { step?; interval?; suffix? } | false | 开启打字机;对象形态可配步长/间隔/光标后缀 |
102
+ | codeTriggerLangs | string[] | | 代码块「预览」触发语言(isMarkdown 模式透传 Markdown) |
103
+ | locale | LocaleInput | undefined | 语言包(透传内嵌 Markdown 的代码块「预览」按钮文案) |
104
+
105
+ | Event | 说明 |
106
+ | --- | --- |
107
+ | start / writing / finish | 开始打字 / 每次推进 / 全部打完 |
108
+
109
+ | Ref | 说明 |
110
+ | --- | --- |
111
+ | interrupt() / continue() / restart() / destroy() | 暂停 / 继续 / 重打 / 重置清空 |
112
+ | renderedContent / isTyping / progress | 已输出文本 / 是否打字中 / 进度 0-1 |
113
+
114
+ ### Bubble
115
+
116
+ 单条气泡(内部按需挂载 Typewriter/Markdown)。
117
+
118
+ | Prop | 类型 | 默认 | 说明 |
119
+ | --- | --- | --- | --- |
120
+ | content | string | '' | 气泡内容 |
121
+ | placement | 'start' \| 'end' | 'start' | start 靠左 / end 靠右 |
122
+ | loading | boolean | false | 加载态(三点动画,可被 #loading 覆盖) |
123
+ | typing | boolean \| TypingConfig | false | 打字机模式(透传 Typewriter) |
124
+ | isMarkdown | boolean | false | 内容按 Markdown 渲染 |
125
+ | isFog | boolean \| { bgColor?; width? } | false | 雾化(自定义气泡背景时传 bgColor) |
126
+ | variant | 'filled' \| 'borderless' \| 'outlined' \| 'shadow' | 'filled' | 气泡样式 |
127
+ | shape | 'round' \| 'corner' | 'round' | 圆角 / 方角 |
128
+ | avatar | string | '' | 头像图片地址 |
129
+ | avatarSize | ElAvatar size \| number | '' | 头像尺寸 |
130
+ | avatarGap | string | '12px' | 头像与内容间距 |
131
+ | avatarShape | 'circle' \| 'square' | 'circle' | 头像形状 |
132
+ | avatarIcon | Component | | 头像图标(与 avatar 冲突时优先) |
133
+ | avatarSrcSet / avatarAlt | string | '' / '' | 头像 srcSet/alt |
134
+ | avatarFit | 'fill' \| 'contain' \| 'cover' \| 'none' \| 'scale-down' | 'cover' | 头像填充方式(el-avatar fit) |
135
+ | noPadding | boolean | false | 内容区去内边距 |
136
+ | noStyle | boolean | false | 去气泡样式(透明/无框/无阴影) |
137
+
138
+ | Event | 说明 |
139
+ | --- | --- |
140
+ | avatar-error | 头像加载失败 |
141
+ | start / writing / finish | typing 模式下的打字机事件透传 |
142
+
143
+ | Slot | 说明 |
144
+ | --- | --- |
145
+ | avatar / header / content / loading / footer | 自定义头像 / 头部 / 内容(优先于 content prop)/ 加载态 / 底部 |
146
+
147
+ | Ref | 说明 |
148
+ | --- | --- |
149
+ | interrupt / continue / restart / destroy | Typewriter 方法转发(非 typing 模式为 no-op) |
150
+ | renderedContent / isTyping / progress | Typewriter 状态转发 |
151
+ | twInstance | 内部 Typewriter 原始实例(BubbleList @complete 透传用) |
152
+
153
+ ### BubbleList
154
+
155
+ 气泡列表 + 吸底/回底按钮。
156
+
157
+ | Prop | 类型 | 默认 | 说明 |
158
+ | --- | --- | --- | --- |
159
+ | list | BubbleListItemProps[] | [] | 列表项(Bubble props + 必填 key) |
160
+ | maxHeight | string | '' | 滚动容器最大高度(如 '350px'/'60vh') |
161
+ | alwaysShowScrollbar | boolean | false | 始终显示滚动条 |
162
+ | showBackButton | boolean | true | 是否显示回底按钮 |
163
+ | backButtonThreshold | number | 80 | 距底超过该像素显示回底按钮 |
164
+ | btnLoading | boolean | false | 回底按钮加载态 |
165
+ | btnColor | string | '' | 回底按钮颜色(el-button color) |
166
+ | backButtonPosition | { bottom?; left? } | {} | 回底按钮位置偏移 |
167
+ | btnIconSize | number | 16 | 回底按钮图标尺寸 |
168
+ | triggerIndices | 'only-last' \| 'all' \| number[] | 'only-last' | @complete 触发索引 |
169
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
170
+
171
+ | Event | 说明 |
172
+ | --- | --- |
173
+ | complete | (typewriterInstance, index) 打字完成(按 triggerIndices 过滤后上抛) |
174
+
175
+ | Slot | 说明 |
176
+ | --- | --- |
177
+ | avatar / header / content / loading / footer | 透传给每个 Bubble,作用域 { item, index } |
178
+
179
+ | Ref | 说明 |
180
+ | --- | --- |
181
+ | scrollToTop() / scrollToBottom() / scrollToBubble(index) | 滚动控制 |
182
+
183
+ ### Sender
184
+
185
+ 输入发送框。
186
+
187
+ | Prop | 类型 | 默认 | 说明 |
188
+ | --- | --- | --- | --- |
189
+ | modelValue | string(v-model) | '' | 输入值(缺省内部自持) |
190
+ | placeholder | string | '' | 占位文案(缺省回落语言包 sender.inputPlaceholder) |
191
+ | autosize | { minRows?; maxRows? } | { minRows: 3, maxRows: 7 } | 自增高(行高 22px;默认 3 行起步,内容多时自动加高至最多 7 行后内部滚动;显式传 {} 退回固定单行) |
192
+ | submitType | 'enter' \| 'shiftEnter' \| 'cmdOrCtrlEnter' \| 'altEnter' | 'enter' | 提交按键模式 |
193
+ | loading | boolean | false | 加载态(发送键变停止键,输入区禁用;停止键出现后 600ms 降险窗口内不可停,吸收发送瞬间的快速连点) |
194
+ | disabled | boolean | false | 禁用(阻断提交) |
195
+ | readOnly | boolean | false | 只读 |
196
+ | clearable | boolean | false | 显示清空按钮 |
197
+ | round | boolean | true | 主按钮(发送/停止)为圆形(element-plus circle;false 时方按钮,停止键光带沿方框流转) |
198
+ | shadow | boolean | false | 输入区阴影效果(浮起感,聚焦时加深) |
199
+ | inputWidth | string | '' | 输入区宽度(variant=default 时有效) |
200
+ | variant | 'default' \| 'updown' | 'default' | default 同排 / updown 上输入下操作栏 |
201
+ | submitBtnDisabled | boolean | false | 附加禁用发送按钮 |
202
+ | triggerStrings | string[] | [] | 指令触发串(光标前命中弹指令框) |
203
+ | triggerPopoverVisible | boolean(v-model:triggerPopoverVisible) | false | 指令弹框显隐 |
204
+ | triggerPopoverWidth / triggerPopoverLeft | string | '' | 指令弹框宽度 / left 偏移 |
205
+ | triggerPopoverOffset | number | 0 | 弹框距触发字符偏移量 |
206
+ | triggerPopoverPlacement | ElPopover placement | 'top-start' | 弹框位置 |
207
+ | allowSpeech | boolean | false | 开启语音输入:麦克风按钮 → 录音条(波形+时长,Esc 取消)→ 确认后转写文本插入光标处;浏览器 SpeechRecognition 实时转写 |
208
+ | allowEmptySubmit | boolean | false | 允许空内容提交(附件场景:只发文件不输文字) |
209
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
210
+
211
+ | Event | 说明 |
212
+ | --- | --- |
213
+ | update:modelValue / change | 输入值变化 |
214
+ | submit | (value) 提交(提交后内部清空) |
215
+ | cancel | 点击停止按钮(loading 翻 true 后 600ms 内的点击被吞不发——防连点误停) |
216
+ | trigger | (keyword, visible) 命中指令串 |
217
+ | recording-change | 语音录制状态变化(预留) |
218
+ | paste-file | (file) 粘贴文件 |
219
+ | update:triggerPopoverVisible | 指令弹框显隐同步 |
220
+
221
+ | Slot | 说明 |
222
+ | --- | --- |
223
+ | header / footer | 头部/底部(配合 ref.openHeader/closeHeader) |
224
+ | prefix | 输入区前缀 |
225
+ | action-list | 自定义操作区(存在时隐藏内置按钮) |
226
+ | action-left | 操作栏左侧附加区(与提交按钮同行靠左,如附件回形针) |
227
+ | trigger | 指令弹框内容(作用域 { keyword }) |
228
+
229
+ | Ref | 说明 |
230
+ | --- | --- |
231
+ | submit() / cancel() / clear() | 提交 / 停止 / 清空 |
232
+ | focus(pos?) / blur() | pos: 'all' 全选 \| 'start' 头 \| 'end' 尾(缺省 end) |
233
+ | openHeader() / closeHeader() | 显隐 #header 插槽 |
234
+
235
+ ### MentionSender
236
+
237
+ 带 @提及 的 Sender(键盘 ↑↓ 导航 / Enter 确认 / Esc 关闭)。
238
+
239
+ | Prop | 类型 | 默认 | 说明 |
240
+ | --- | --- | --- | --- |
241
+ | modelValue | string(v-model) | '' | 输入值 |
242
+ | userList | MentionUserInfo[] | [] | @ 触发的候选用户(id/name/avatar/pinyin) |
243
+ | customTrigger | MentionCustomTrigger[] | [] | 自定义触发组 { dialogTitle, prefix, tagList } |
244
+ | asyncMatchFun | (search) => Promise<MentionUserInfo[]> | — | 异步候选(存在时防抖 300ms,后端过滤) |
245
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(候选加载文案);内嵌 Sender 的文案经祖先注入(如 AiChat)或全局设置生效 |
246
+
247
+ 事件:`update:modelValue` / `change` / `submit` / `cancel` / `trigger` / `recording-change` / `paste-file` / `update:triggerPopoverVisible` / `show-at-dialog`(弹层显隐);其余 props/事件经 `$attrs` 透传给 Sender,slot 经 forwardedSlots 显式转发(header/footer/prefix/action-list/trigger)。
248
+
249
+ | Ref | 说明 |
250
+ | --- | --- |
251
+ | submit / cancel / clear / focus / blur / openHeader / closeHeader | Sender 方法转发 |
252
+ | setUserTag(userId) | 光标处程序化插入 @用户 |
253
+ | setCustomTag(prefix, id) | 光标处插入自定义触发标签 |
254
+
255
+ ### EditorSender
256
+
257
+ 富文本标签编辑器(contenteditable),open-webui 风格标签芯片。
258
+
259
+ | Prop | 类型 | 默认 | 说明 |
260
+ | --- | --- | --- | --- |
261
+ | placeholder | string | '' | 占位文案 |
262
+ | device | 'pc' \| 'h5' | 'pc' | 设备形态(仅影响样式) |
263
+ | autoFocus | boolean | false | 挂载后聚焦到末尾 |
264
+ | variant | 'default' \| 'updown' | 'default' | 布局形态 |
265
+ | userList | EditorUser[] | [] | @ 候选用户 |
266
+ | customTrigger | EditorCustomTrigger[] | [] | 自定义触发组 |
267
+ | selectList | EditorSelectGroup[] | [] | 选择标签分组(openSelectDialog 弹窗数据) |
268
+ | maxLength | number | 0 | 纯文本最大长度(0 不限;性能开销大,仅显式开启) |
269
+ | submitType | 'enter' \| 'shiftEnter' | 'enter' | 提交按键模式 |
270
+ | customStyle | Record<string, any> | {} | 根节点自定义样式 |
271
+ | loading | boolean | false | 加载态(发送键变停止键) |
272
+ | disabled | boolean | false | 禁用 |
273
+ | clearable | boolean | false | 显示清空按钮 |
274
+ | headerAnimationTimer | number | 300 | 头部过渡时长(ms) |
275
+ | asyncMatchFun | (search) => Promise<EditorUser[]> | | 异步 @ 候选(防抖 300ms) |
276
+ | customDialog | boolean | false | 选择标签不自弹内置弹窗,仅上抛 show-select-dialog |
277
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
278
+
279
+ | Event | 说明 |
280
+ | --- | --- |
281
+ | submit / change | (SubmitResult) SubmitResult = { text, html, tags: { userTags, selectTags, inputTags, customTags } } |
282
+ | cancel | 点击停止按钮 |
283
+ | show-at-dialog / show-select-dialog / show-tag-dialog | 各弹层显隐 |
284
+
285
+ | Slot | 说明 |
286
+ | --- | --- |
287
+ | header / footer / prefix / action-list | 同 Sender |
288
+ | tag-tip | 输入标签 tip 弹层内容(作用域 { nodeId }) |
289
+
290
+ | Ref | 说明 |
291
+ | --- | --- |
292
+ | getCurrentValue() | 取 { text, html, tags } |
293
+ | focusToStart() / focusToEnd() / blur() / selectAll() / clear() | 光标与清空 |
294
+ | setText(text) / setHtml(html) / setMixTags(rows) | 程序化写入 |
295
+ | setUserTag(id) / setCustomTag(prefix, id) / setInputTag(id, name) / setSelectTag(list) | 插入各类标签 |
296
+ | customSetUser(user) / customSetTag(tag) | 外部直传对象插入(不经列表查表) |
297
+ | updateSelectTag(method, options) | 选择标签更新:'insertTag'/'updateTagValue'/'deleteTag'/'updateTagStyle' |
298
+ | openSelectDialog() / openTipTag(nodeId?) / closeTipTag() | 弹窗控制 |
299
+ | openHeader() / closeHeader() | 显隐 #header |
300
+ | chat / opNode(method, options) / chatState() | 底层文档模型:chat.insert/update/delete/append;opNode 按方法名分发 |
301
+
302
+ ### Thinking
303
+
304
+ 思考链折叠面板。
305
+
306
+ | Prop | 类型 | 默认 | 说明 |
307
+ | --- | --- | --- | --- |
308
+ | modelValue | boolean(v-model) | false | 展开/收起 |
309
+ | content | string | '' | 思考内容(常配合 #content 插槽嵌 FvMarkdown) |
310
+ | status | 'start' \| 'thinking' \| 'end' \| 'interrupted' \| 'error' | 'start' | 思考状态(interrupted 为用户中断态,警告橙图标) |
311
+ | disabled | boolean | false | 禁用切换 |
312
+ | autoCollapse | boolean | false | status 变为 end 时自动收起 |
313
+ | hideHeader | boolean | false | 隐藏折叠头(单 item 链平铺形态):不渲染切换按钮,内容区常驻展开 |
314
+ | buttonWidth | string | '' | 切换按钮区宽度 |
315
+ | maxWidth | string | '' | 内容区最大宽度 |
316
+ | color / backgroundColor | string | '' | 前景色 / 背景色 |
317
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
318
+
319
+ | Event | 说明 |
320
+ | --- | --- |
321
+ | update:modelValue | 展开/收起同步 |
322
+
323
+ | Slot | 说明 |
324
+ | --- | --- |
325
+ | status-icon / label / arrow | 自定义状态图标 / 文案 / 箭头 |
326
+ | content / error | 思考内容 / error 态内容 |
327
+
328
+ | Ref | 说明 |
329
+ | --- | --- |
330
+ | modelValue / toggle() | 展开状态 / 手动切换 |
331
+
332
+ ### ThoughtChain
333
+
334
+ 思维链步骤条。text 步(kind: 'text')为「正在思考/思考完成」标题行 + 可折叠 description 滚动区(默认收起;展开时 ElScrollbar 限高 269px,流式期间自动滚底;内容被滚动裁掉的方向在上/下缘渲染 35px 渐隐条 `scroll-edge-fade-top` / `scroll-edge-fade-bottom`,贴顶/贴底各自隐藏);工具步 kind: 'tool' 为普通步骤行。
335
+
336
+ | CSS 变量 | 默认 | 说明 |
337
+ | --- | --- | --- |
338
+ | --fv-chain-edge-fade-color | var(--el-bg-color) | text 步滚动区上/下缘渐隐条颜色(默认跟随页面底色,暗色模式经 element-plus 变量自动适配;思考链叠在非底色卡片上时可覆盖) |
339
+
340
+ | Prop | 类型 | 默认 | 说明 |
341
+ | --- | --- | --- | --- |
342
+ | items | ThoughtChainItem[] | [] | 步骤项 { key, title?, status?: 'pending'/'success'/'loading'/'error', icon?, description?, kind?: 'tool'/'text', typing?, closed? } |
343
+ | direction | 'vertical' \| 'horizontal' | 'vertical' | 排列方向 |
344
+ | collapsible | boolean | false | 工具步长文案展开/收起(超 3 行截断 + 行尾「展开」) |
345
+ | showDuration | boolean | false | 显示工具步用时 description(text 步 description 不受影响) |
346
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
347
+
348
+ | Slot | 说明 |
349
+ | --- | --- |
350
+ | content | 覆盖默认 title/description(作用域 { item, index }) |
351
+
352
+ ### Welcome
353
+
354
+ 空态欢迎页。icon/name/description 均未传时显示内置品牌默认欢迎(「你好,我是 Gizmo」问候高亮 + IP 形象动图 + 默认描述),逐 prop 独立覆盖。
355
+
356
+ 结构:图标区(DOM 序在前)+ 主列(`.fv-welcome-main`:文案列 + 建议区);纵排图标居中显示在文案上方;横排主列为唯一文档流内容(左对齐),吉祥物浮层悬于文案右上(经 flex order 排到主列右侧)——建议区与文案同列,不会把吉祥物顶高。
357
+
358
+ | Prop | 类型 | 默认 | 说明 |
359
+ | --- | --- | --- | --- |
360
+ | icon | string \| Component | '' | 图标(字符串为图片地址;未传渲染内置品牌欢迎动图,横排/纵排同图,仅尺寸不同:横排大图 108px×scale1.8,纵排 96px) |
361
+ | name | string | '' | 名称(未传回落内置问候语「你好,我是 Gizmo」) |
362
+ | description | string | '' | 描述(纯文本;未传回落内置默认描述) |
363
+ | layout | 'vertical' \| 'horizontal' | 'vertical' | 布局:vertical 纵排(吉祥物居中在文案上方)/ horizontal 横排(文案左对齐,欢迎吉祥物浮层悬于文案右上,空态欢迎形态,原型 .intro 同构) |
364
+ | locale | LocaleInput | undefined | 语言包(内置欢迎文案) |
365
+
366
+ | Slot | 说明 |
367
+ | --- | --- |
368
+ | icon / name / description | 覆盖对应区块 |
369
+ | suggestions | 建议区(AiMessages 在此渲染 Prompts 快捷条;横排时与文案同列靠左) |
370
+
371
+ ### CSS 变量
372
+
373
+ | CSS 变量 | 默认 | 说明 |
374
+ | --- | --- | --- |
375
+ | --fv-welcome-icon-size | 纵排 96px | 内置品牌动图尺寸(纵排;横排吉祥物固定 108px×scale1.8 对齐原型) |
376
+ | --fv-welcome-max-width | 780px | 空态欢迎块宽度(AiMessages 空态轴线;文案/吉祥物/快捷条共用。AiChat 整框内空态时与输入区同轴,回落 --fv-empty-max-width;独立使用 AiMessages 时为 780px,可覆盖) |
377
+ | --fv-welcome-desc-max-width | 590px | 横排描述文字最大宽度(原型 .intro p) |
378
+
379
+ ### Prompts
380
+
381
+ 建议 prompt 网格。
382
+
383
+ | Prop | 类型 | 默认 | 说明 |
384
+ | --- | --- | --- | --- |
385
+ | prompts | PromptItem[] | [] | 建议项 { key(必填), label?, description?, icon?(EP 图标名字符串或组件), disabled? } |
386
+ | title | string | '' | 网格标题 |
387
+ | wrap | boolean | true | 换行模式(默认 true 自动换行;false 不换行,超出部分横向滚动) |
388
+
389
+ | Event | 说明 |
390
+ | --- | --- |
391
+ | select | (item) 点击(disabled 项不触发) |
392
+
393
+ | Slot | 说明 |
394
+ | --- | --- |
395
+ | default | 覆盖整卡(作用域 { item, index }) |
396
+
397
+ ### FilesCard
398
+
399
+ 单个文件卡片。文档模式按扩展名自动映射**设计稿类型图标**(f-*.svg):xlsx/xls/csv 等表格→excel、pdf→pdf、pptx/ppt→ppt、docx/doc/wps→word、txt/md/json/log 等文本→txt,未命中回落通用 file 图标;图标 fill=currentColor 随主题色走。
400
+
401
+ | Prop | 类型 | 默认 | 说明 |
402
+ | --- | --- | --- | --- |
403
+ | name | string | '' | 文件名 |
404
+ | fileType | 'image' \| 'file' | 'file' | image 渲染缩略图,file 渲染类型图标卡 |
405
+ | size | number \| string | 0 | 文件大小(字节自动格式化为 B/KB/MB;字符串原样展示;0 不显示) |
406
+ | url | string | '' | 图片地址(image 模式缩略图) |
407
+ | status | 'loading' \| 'success' \| 'error' | 'success' | loading:图标位换 spinner + 名称行下「上传中…」(卡内显示);error 红边 + 失败原因 |
408
+ | errorText | string | '' | 失败原因红字(error 态展示于卡片下方,超宽截断 title 全文) |
409
+ | imageSize | string | '' | 缩略图尺寸(width/height 同值) |
410
+ | onDelete | () => void | — | 删除按钮回调(按钮常驻右上角,hover 浮现) |
411
+ | onDownload | () => void | — | 下载回调:注入时右上角渲染下载按钮(28px hover 浮现,比删除按钮大一圈,垂直居中)。消息附件卡走此路(内置触发浏览器下载),输入区附件卡不注入 |
412
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
413
+
414
+ | Slot | 说明 |
415
+ | --- | --- |
416
+ | image | 覆盖图片区(默认 url 缩略图,无 url 渲染 Picture 占位) |
417
+
418
+ ### Attachments
419
+
420
+ 附件选择与列表(v-model)。
421
+
422
+ | Prop | 类型 | 默认 | 说明 |
423
+ | --- | --- | --- | --- |
424
+ | modelValue | object[](v-model) | [] | 附件列表(项含 uid/name/size/url/fileType/status/raw) |
425
+ | accept | string | '' | input accept,如 'image/*' |
426
+ | tip | string | '' | 内联提示文案 |
427
+ | count | number | 0 | 最大附件数(超出走 @exceed;0 不限) |
428
+ | beforeUpload | (file) => boolean \| Promise<boolean> | | 上传前校验,返回 false 拦截 |
429
+ | upload | (file, item) => Promise\<Partial\<AttachmentItem\> \| undefined \| void\> \| ... | | 上传钩子(先传后发):选文件即调——入列即 loading,成功返回附件描述(含服务端附件 id)回填列表项置 success,失败(抛错/resolve 错误文案串)置 error 带失败原因(可重传再走钩子);缺省不调(纯本地待发列表,入列直接 success) |
430
+ | disabled | boolean | false | 整体禁用(触发按钮不可点;生成中锁定输入场景,单飞行闸语义) |
431
+ | layout | 'inline' \| 'triggerOnly' \| 'listOnly' | 'inline' | 布局:inline 回形针+列表+提示一行;triggerOnly 只渲染回形针按钮;listOnly 只渲染文件列表(拆分布局供整框组合:按钮进操作栏、列表进输入区上方) |
432
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
433
+
434
+ | Event | 说明 |
435
+ | --- | --- |
436
+ | update:modelValue / change | 列表变化(全量数组) |
437
+ | exceed | (file) 超出 count |
438
+ | delete | (item) 删除某项 |
439
+ | uploaded | (item, result?) 上传钩子落定(单项):成功回填后的列表项 + 上传结果;失败时 result 为 undefined(失败原因在 item.errMessage,FilesCard 红字展示) |
440
+
441
+ | Slot | 说明 |
442
+ | --- | --- |
443
+ | list-item | 覆盖项渲染(作用域 { item, index }) |
444
+ | list-thumb | 覆盖图片缩略图(作用域 { item, index }) |
445
+
446
+ | Ref | 说明 |
447
+ | --- | --- |
448
+ | openSelect() | 程序化打开文件选择 |
449
+ | retry(item) | error 项重新置为 loading(上传逻辑由外部接线) |
450
+
451
+ ### Conversations
452
+
453
+ 会话列表(按 group 分组)。
454
+
455
+ | Prop | 类型 | 默认 | 说明 |
456
+ | --- | --- | --- | --- |
457
+ | items | ConversationItem[] | [] | 会话项 { key(必填), label(必填), group?, disabled? } |
458
+ | active | string \| number(v-model:active) | undefined | 当前激活会话 key |
459
+ | showBuiltInMenuType | 'hover' \| 'always' | 'hover' | 内置菜单按钮显隐方式 |
460
+ | groupable | (a, b) => number | — | 分组排序比较器(缺省保持插入顺序) |
461
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
462
+
463
+ | Event | 说明 |
464
+ | --- | --- |
465
+ | update:active / change | 选中会话(key / item) |
466
+ | menu-command | ({ item, command: 'rename'/'delete', value? }) 菜单指令;rename 确认后带新名称 |
467
+
468
+ | Slot | 说明 |
469
+ | --- | --- |
470
+ | group-title | 分组标题(作用域 { group }) |
471
+ | item | 覆盖行内容(作用域 { item, active }) |
472
+ | menu | 覆盖菜单项(默认重命名/删除;作用域 { item }) |
473
+
474
+ | Ref | 说明 |
475
+ | --- | --- |
476
+ | handleMenuCommand({ item, command }) | 程序化触发菜单指令转发(纯转发,同步上抛 menu-command) |
477
+ | renamePrompt(key) | 弹重命名输入框,确认后上抛 menu-command |
478
+ | deleteConfirm(key) | 弹删除确认框,确认后上抛 menu-command |
479
+
480
+ ### FvBlobHalo
481
+
482
+ blob 光晕(FvBlobHalo,基础组件):多色模糊「色团」氛围光——内联 SVG 8 个 blob(每色一组正体 + alt 淡体),path 以 `d: path()` 关键帧在形状配方间连续变形(蠕变),每个色团各自异速旋转,全部居中叠放:中心混色、随转动流动;**第 4 槽位是高光位**(fill 走径向渐变,中心实色 → 向外透明渐大,模拟高光柔光)。FvAiChatLauncher 内嵌同款效果;亦可独立用在任意需要氛围光的场景(装饰背景、头像/卡片区光效等)。无定位(inline-flex 占位,`pointer-events: none`),挂载位置与层叠由使用方决定。
483
+
484
+ ```vue
485
+ <FvBlobHalo :size="88" :opacity="0.8" :colors="['#ff8c42', '#fcaf58', '#f9c784', '#ffffff']" />
486
+ ```
487
+
488
+ | Prop | 类型 | 默认 | 说明 |
489
+ | --- | --- | --- | --- |
490
+ | colors | (string \| FvBlobHaloColor \| null)[] | 主题色 + AI 紫(#bb74ff)+ 浅紫(#a78bfa)+ 白 | 色团色板,每色一组正体 + alt 淡体,最多 4 色;槽位传色值字符串或 `{ color, opacity?, altOpacity?, mid?, scale? }` 对象(按色覆盖透明度/高光渐变/缩放,缺省回落内置);`null`/`undefined` 保留默认色(部分自定义) |
491
+ | size | number | 88 | 光晕尺寸(px,正圆直径) |
492
+ | scale | number | 1 | 相对放大倍率(>1 越出挂载盒,需使用方容器 overflow 可见) |
493
+ | opacity | number | 0.8 | 正体透明度(0~1) |
494
+ | altOpacity | number | 0.35 | alt 淡体透明度(0~1) |
495
+ | rotateDuration | number | 25 | 旋转一周时长(s;各槽位按内置比例差异化;0 停转只留变形蠕动) |
496
+ | paused | boolean | false | 暂停全部动画(静帧装饰) |
497
+
498
+ 说明:
499
+
500
+ - 第 4 槽位为「高光位」:fill 用径向渐变(中心 100% 实色 → 半径 50% 处浓度 `mid`(默认 .45)→ 边缘全透明),自带「中心实、向外透明渐大」的高光过渡;`mid` 越小淡出越快;其余槽位彩团平涂色 + blur(叠色饱满)
501
+ - 色板槽位有内置「角色」:第 1 色大清晰(主题位,scale .8)、第 2/3 色更小更快(辅色位,.78/.76)、第 4 色即高光位(.62);槽位对象 `scale` 可按色覆盖缩放
502
+ - 按色调透明度/缩放:`:colors="[null, { color: '#ff0000', opacity: 1, scale: 0.6 }]"`(对象槽位;缺省项回落内置)
503
+ - 默认色板中的 AI 紫可用 CSS 变量 `--fv-blob-purple`/`--fv-blob-purple-2` 覆盖(无需传 colors)
504
+ - `prefers-reduced-motion` 下自动停动
505
+ - `d: path()` 变形仅 Chromium 支持,其他内核形状静止在初始形(旋转照常);path 带初始 `d` 兜底可渲染
506
+
507
+ ### FvSvgIcon
508
+
509
+ 通用 SVG 图标(FvSvgIcon,基础组件):按 `name` 引用库内 `assests/icons/<name>.svg`,以 `?raw` 源文本**内联渲染**(v-html)——svg 吃 CSS 继承,`fill="currentColor"` 强制覆写,颜色随文字色/亮暗主题/hover 态走(这是不用 `<img src>` 的原因:外部文档吃不到 currentColor)。**换图标只替换 `assests/icons/` 里的 svg 文件,代码零改动;新增图标丢文件进目录即自动可用**(构建期 glob 收集)。svg 文件内的 `width`/`height`(设计稿常见 `width="200"`)与硬编码 `fill`/`class` 会被剥除,统一由组件控制尺寸;`viewBox` 保留。
510
+
511
+ ```vue
512
+ <FvSvgIcon name="maximize" :size="18" />
513
+ ```
514
+
515
+ | Prop | 类型 | 默认 | 说明 |
516
+ | --- | --- | --- | --- |
517
+ | name | string | (必填) | 图标名(`assests/icons/` 下文件名去扩展名;内置 bulb/dislike[-filled]/f-{excel,pdf,ppt,word,txt,file}/like[-filled]/maximize/sidebar/sparkle/to-{window,drawer}/win-restore) |
518
+ | size | number \| string | 16 | 尺寸:number 按 px;字符串原样透传(如 '1em' 跟字号) |
519
+
520
+ 另导出 `iconRegistry`(`Record<string, string>`,name → svg 源文本映射),可查询可用图标名或取源文本自行处理。
521
+
522
+ ## 对话应用层 API
523
+
524
+ ### AiChat
525
+
526
+ 对话整框:顶栏(标题+模型多选)、消息区(空态 Welcome/Prompts)、输入区(Sender)、可选 Artifacts 面板。
527
+
528
+ | Prop | 类型 | 默认 | 说明 |
529
+ | --- | --- | --- | --- |
530
+ | model | string | '' | 默认模型(未传 models 时作为单模型) |
531
+ | models | string[] | [] | 可选模型列表(有值时顶栏多选选择器) |
532
+ | baseURL | string | '' | OpenAI 兼容服务地址(未传 adapter 时构造 OpenAIAdapter) |
533
+ | apiKey | string | '' | 服务密钥 |
534
+ | adapter | ChatAdapter | undefined | 聊天适配器(与 baseURL 二选一,优先) |
535
+ | messages | MessageNode[](v-model:messages) | undefined | 消息链(半受控,见下) |
536
+ | title | string | '' | 顶栏标题(同时作空态欢迎页名称;未传时欢迎页显示内置默认问候「你好,我是 Gizmo」) |
537
+ | showHeader | boolean | false | 显示顶栏(标题 + 模型选择器;models 多选选择器在顶栏内,需开启才可见) |
538
+ | centerWelcome | boolean | true | 空态居中:未开始对话时欢迎内容与输入区整体垂直居中,首条消息后输入区恢复固定底部 |
539
+ | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(透传 AiMessages;距底超过 scrollButtonThreshold 时出现) |
540
+ | scrollButtonThreshold | number | 100 | 滚到底部悬浮按钮显示阈值(px,透传 AiMessages) |
541
+ | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px,透传 AiMessages):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动;调小可恢复更灵敏的跟随 |
542
+ | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;false 时用户消息不渲染头像;助手头像不受影响) |
543
+ | showUserName | boolean | false | 显示用户名称(默认隐藏;false 时用户消息不渲染头部名称行;助手名称不受影响) |
544
+ | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像;用户头像不受影响) |
545
+ | showAssistantName | boolean | false | 显示助手名称(默认隐藏;false 时助手消息不渲染头部名称行;用户名称不受影响) |
546
+ | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标;`user-avatar` 插槽优先) |
547
+ | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif;`assistant-avatar` 插槽优先) |
548
+ | assistantAvatarScale | number | 1 | 助手头像缩放系数(默认 1 不缩放;亦可用 CSS 变量 --fv-msg-avatar-scale 覆盖,prop 优先) |
549
+ | avatarCircle | boolean | true | 头像圆形模式(默认 true:圆角 50%;false 回落默认圆角;亦可用 CSS 变量 --fv-msg-avatar-radius 直接覆盖圆角取值,变量优先于开关) |
550
+ | userName | string | '' | 用户名称(空串回落「你」;`user-name` 插槽优先) |
551
+ | assistantName | string | '' | 助手名称(空串回落「Gizmo」;`assistant-name` 插槽优先) |
552
+ | placeholder | string | '' | 输入框占位(缺省回落语言包 sender.inputPlaceholder:zh「输入你的问题,查询数据、分析问题或生成报表…」) |
553
+ | senderAutosize | { minRows?; maxRows? } | { minRows: 3, maxRows: 7 } | 输入区自增高(透传 Sender autosize;默认 3 行起步,内容多时自动加高至最多 7 行后内部滚动) |
554
+ | toolStepLabel | (toolName) => string | undefined | 工具名 → 步骤展示名(透传 useChat toolStepLabel) |
555
+ | typing | boolean \| { step?; interval? } | false | 打字机(透传 AiMessages;仅 assistant 流式期间逐字平滑打出,落定/历史消息整段渲染) |
556
+ | autoCollapse | boolean | true | 正文出完自动收起思考链(透传 AiMessage;status 落 done 且正文打完才收;error 不收) |
557
+ | collapsible | boolean | false | 思考链工具步长文案展开/收起(透传 ThoughtChain;超 3 行截断 + 行尾「展开/收起」) |
558
+ | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
559
+ | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:`message.createdTime`——Fv 系后端直灌,秒级/毫秒级时间戳或 ISO 字符串自动识别——优先,缺省回落 `message.createdAt`。助手消息 SSE 生成中不显示,正文打完字(未启用打字机则落定)后才显示;error 即显;user 消息恒显示) |
560
+ | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
561
+ | senderShadow | boolean | true | 输入区阴影效果(透传 Sender 的 shadow) |
562
+ | suggestions | AiChatSuggestion[] | [] | 空态建议列表(Prompts 项,key 必填;空态快捷条为胶囊形态,description 不显示) |
563
+ | suggestionsWrap | boolean | true | 空态建议换行模式(true 自动换行;false 不换行,超出横向滚动) |
564
+ | welcomeLayout | 'horizontal' \| 'vertical' | 'horizontal' | 空态欢迎页布局(透传 AiMessages→Welcome):horizontal 横排(默认)/ vertical 纵排(悬浮窗等窄宽场景) |
565
+ | followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式(透传 AiMessages→AiMessage):'list' 纵向列表一行一条,渲染在回答操作区下方,顶部浅灰分隔线 + 「追问」标题(不加粗,与正文同色,字号随正文,标题文案经语言包 `aiMessage.followupsTitle` 自定义),条目 100% 宽、下划线分隔(浅灰,末条不出线)、字号随正文、文案次级灰,历史消息同样渲染;'chips' 为旧横向气泡形态(换行铺排,无标题)。**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示,落定+打完字整体浮现) |
566
+ | features | AiChatFeatures | {} | 特性开关 { artifacts?, tts?, queue?, continueGenerate?, fullscreenEditor? }(当前仅 artifacts 生效);artifacts 传 `true` 用默认配置,传对象 `{ width?, minWidth?, maxWidth?, autoOpen?, codeBlockTrigger? }` 自定义:宽度三参控面板尺寸(默认 420px/360px/60%),autoOpen(默认 true)检测到代码块自动弹面板,codeBlockTrigger(默认 true)在消息 html/svg 代码块右上角显示「预览」按钮、点击打开对应面板 |
567
+ | allowAttachments | boolean | false | 开启输入区附件上传(回形针在操作栏左侧与提交按钮同行,已选列表在输入框上方;只传附件不输文字也可提交) |
568
+ | accept | string | '' | 附件 input accept 属性(透传 Attachments),如 `image/*,.pdf,.txt`。缺省 '' 不限制(zip/exe 等是否可传由消费方自主决定);显式传值时除选择器过滤外组件内注入 beforeUpload 硬校验——白名单外文件(选择器切「所有文件」绕过 accept)不入列,自动 toast 提示(文案经语言包 `errors.attachmentRejected` 自定义,`{name}` 为文件名)并上抛 @attachment-reject |
569
+ | attachmentLimit | number | 0 | 附件数量上限(0 不限,超限走 @attachment-exceed) |
570
+ | uploadAttachment | (file, item) => Promise\<Partial\<AttachmentItem\> \| string \| undefined \| void\> \| ... | undefined | 附件上传钩子(先传后发):选文件即调,成功返回附件描述(id/name/type 等回填列表项,id 随发送进入 adapter 的 user 消息 files);返回错误文案串/抛错置 error 可重传。缺省不调(附件仅本地待发展示,不落服务端);上传中(loading 项)提交按钮禁用拒发,error 残留项不随发送 |
571
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(鉴权取流):消息气泡渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址)。远端 url 解析结果组件内按 url 缓存 + 在途去重;解析失败回落原 url 不阻塞渲染 |
572
+ | feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessages→AiMessage;仅 assistant 最终回答行渲染 👍/👎,缺省不渲染按钮)。消费方在此接后端评价端点(如 Fv 系 POST /message/feedback):resolved 即成功;返回错误文案串/抛错触发 feedback-error(乐观更新已回滚);action=CLEAR 取消评价(comment 忽略)。交互语义:点击 👍 直接提交(不弹附言),点击 👎 弹**居中附言弹窗**(textarea ≤500 字 + 提交/跳过),再次点击当前态按钮发 CLEAR 取消评价(附言一并清空);👍↔👎 任意切换,后一次整体覆盖前一次(含附言);提交中按钮禁用防连点 |
573
+ | theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题(向 html 注入/移除 dark class) |
574
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(解析后注入整框后代) |
575
+
576
+ **v-model:messages 半受控语义**:外部 `messages` 仅在 setup 时一次性深拷贝灌入(用于恢复历史);组件内部每次变更全量上抛 `update:messages`(同帧去抖),父组件需经 v-model 回写维持单向数据流;父组件后续直接改 prop **不会**回灌生效。
577
+
578
+ | Event | 说明 |
579
+ | --- | --- |
580
+ | update:messages | (MessageNode[]) 全量消息链(去抖后) |
581
+ | send | (text, files?) 用户发送(allowAttachments 开启时 files 为降维后的 ChatFile[]) |
582
+ | suggestion-select | (item) 点击空态建议项(先于 send 触发;label 为空的项不发) |
583
+ | followup-select | (item, message) 点击回答尾部追问建议(先于 send 触发;组件内部已接住转 send 开启新一轮,事件仅供消费方可观测/埋点;assistant 消息带 suggestions 即渲染,不再限链尾——历史消息同样显示;正文打字效果完成后才渲染) |
584
+ | message-complete | (message) 链尾 assistant 生成完成 |
585
+ | error | (err, message?) 生成出错 |
586
+ | branch-change | (dir, message) 分支切换 |
587
+ | attachment-exceed | (file) 附件超过 attachmentLimit 上限 |
588
+ | attachment-reject | (file) 附件被类型白名单拦截(显式 accept 的白名单外文件,如 zip/exe;文件选择器切「所有文件」绕过 accept 时由 beforeUpload 兜底拦截)。组件已自动 toast 提示,事件仅供消费方埋点/追加处理 |
589
+ | attachment-uploaded | (item, { ok, message? }) 附件上传钩子落定(allowAttachments + uploadAttachment 场景):ok=false 时 message 为失败原因,宿主可 toast/埋点 |
590
+ | message-file-click | (file, message) 点击消息气泡附件 chips:默认行为——图片类经 resolveFileUrl 解析后打开内置 ElImageViewer 放大(同消息多图轮播),文档类无内置行为,宿主接此事件自行下载 |
591
+ | feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新),宿主可埋点/联动 |
592
+ | feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
593
+ | scroll | (event) 消息区滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
594
+
595
+ | Slot | 说明 |
596
+ | --- | --- |
597
+ | message-avatar / message-actions | 透传给 AiMessages(作用域见 AiMessage;message-avatar 优先于细分头像插槽) |
598
+ | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
599
+ | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
600
+ | welcome-name / welcome-description / welcome-icon | 单独配置欢迎页主标题/描述/吉祥物(转发 Welcome 同名插槽;优先于 title 等默认文案) |
601
+ | welcome-suggestions | 单独配置欢迎页建议区(整体替换默认 Prompts 快捷条;建议渲染在文案下方与文案同列) |
602
+ | empty | 覆盖空态整区 |
603
+ | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
604
+ | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
605
+ | sender-prefix | 输入区前缀 |
606
+
607
+ | CSS 变量 | 默认 | 说明 |
608
+ | --- | --- | --- |
609
+ | --fv-empty-max-width | 780px | 空态(welcome 态)轴线最大宽度:欢迎块/快捷条与输入区(Sender)共用同轴线,宽屏居中;仅空态生效,首条消息后恢复全宽 |
610
+ | --fv-msg-avatar-size | 50px | 消息头像块边长(宽高同值;内置图标字号随块尺寸自适应) |
611
+ | --fv-msg-avatar-radius | 50%(avatarCircle 默认开) | 消息头像圆角(avatarCircle=false 时回落默认圆角;直接赋值可自定义任意圆角,优先于开关) |
612
+ | --fv-msg-avatar-scale | 1 | 助手头像缩放系数(默认 1 不缩放;放大可裁掉图片四周留白;assistantAvatarScale prop 优先于此变量) |
613
+
614
+ | Ref | 说明 |
615
+ | --- | --- |
616
+ | sendMessage(text, files?) | 程序化发送 |
617
+ | stop() | 停止生成(保留半截内容,静默收口不发 complete/error) |
618
+ | regenerate(messageId?) | 重生成(缺省链尾 assistant) |
619
+ | appendToMessage(id, text) | 向指定消息追加文本 |
620
+ | clearMessages() | 清空消息树 |
621
+ | exportTxt() | 导出当前链为纯文本 |
622
+ | openArtifact(key) | 程序化打开某个 artifact |
623
+ | expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链(user 消息、无思考链消息、单 item 平铺形态不受控) |
624
+ | scrollTo(options) | 消息区滚动到指定位置(options 同原生 ScrollToOptions,如 { top: 0, behavior: 'smooth' };也可传 number) |
625
+
626
+ ### AiMessages
627
+
628
+ 消息列表(空态渲染 Welcome,建议快捷条经 Welcome #suggestions 插槽渲染在文案下方),吸底滚动。
629
+
630
+ | Prop | 类型 | 默认 | 说明 |
631
+ | --- | --- | --- | --- |
632
+ | messages | MessageNode[] | (必填) | 当前链消息(根 → 焦点) |
633
+ | nodes | Record<string, MessageNode> | {} | 全量节点表(分支计算需查父 childrenIds) |
634
+ | icon | string \| Component | '' | 空态欢迎页图标 |
635
+ | name | string | '' | 空态欢迎页名称 |
636
+ | description | string | '' | 空态欢迎页描述 |
637
+ | suggestions | AiMessagesSuggestion[] | [] | 空态建议列表 |
638
+ | suggestionsTitle | string | '' | 空态建议区标题 |
639
+ | suggestionsWrap | boolean | true | 空态建议换行模式(true 自动换行;false 不换行,超出横向滚动) |
640
+ | scrollThreshold | number | 100 | 用户上滚免打扰阈值(px):距底不超过该值视为「钉在底部」,流式期间自动跟随滚动 |
641
+ | showScrollButton | boolean | true | 显示滚到底部悬浮按钮(空态不渲染) |
642
+ | scrollButtonThreshold | number | 100 | 距底超过该值(px)才显示滚到底部悬浮按钮 |
643
+ | showActions | boolean | true | 显示消息操作按钮(复制/重生成;生成中 pending/streaming 不渲染) |
644
+ | showBranchSwitch | boolean | true | 显示分支切换器 |
645
+ | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;助手头像不受影响) |
646
+ | showUserName | boolean | false | 显示用户名称(默认隐藏;助手名称不受影响) |
647
+ | showAssistantAvatar | boolean | true | 显示助手头像(用户头像不受影响) |
648
+ | showAssistantName | boolean | false | 显示助手名称(默认隐藏;用户名称不受影响) |
649
+ | userAvatar | string | '' | 用户头像图片 URL(透传 AiMessage) |
650
+ | assistantAvatar | string | '' | 助手头像图片 URL(透传 AiMessage;传入完全覆盖不分状态,空串按状态回落内置 GIF) |
651
+ | assistantAvatarScale | number | 1 | 助手头像缩放系数(透传 AiMessage;默认 1 不缩放) |
652
+ | userName | string | '' | 用户名称(透传 AiMessage) |
653
+ | assistantName | string | '' | 助手名称(透传 AiMessage;空串回落「Gizmo」) |
654
+ | showTime | boolean | true | 显示消息时间(透传 AiMessage;时间源 createdTime 优先,缺省回落 createdAt。助手消息生成中不显示,打完字后才显示) |
655
+ | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传 AiMessage) |
656
+ | autoCollapse | boolean | true | 正文出完自动收起思考链(透传 AiMessage;status 落 done 且正文打完才收;error 不收) |
657
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子(透传 AiMessage;鉴权取流换可直渲地址,见 AiChat) |
658
+ | followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式(透传 AiMessage;默认 'list' 纵向列表——顶部灰色分隔线 + 加粗「追问」标题(字号/颜色随正文)、条目 100% 宽下划线分隔字号随正文;'chips' 旧横向气泡,见 AiChat)。**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示) |
659
+ | feedbackHandler | (message, action, comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子(透传 AiMessage;语义见 AiChat,缺省不渲染 👍/👎) |
660
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
661
+
662
+ | Event | 说明 |
663
+ | --- | --- |
664
+ | select / copy / regenerate / branch-change | 建议选中 / 复制 / 重生成 / 分支切换,载荷同 AiChat |
665
+ | followup-select | (item, message) 点击追问建议 chip(透传 AiMessage,载荷同 AiChat) |
666
+ | message-file-click | (file, message) 点击消息附件 chips(透传 AiMessage;图片类默认打开内置放大预览,文档类宿主自行下载) |
667
+ | feedback-change / feedback-error | 评价提交成功(message, action)/ 失败(错误文案;透传 AiMessage,语义见 AiChat) |
668
+ | scroll | (event) 滚动容器滚动(原生 scroll 事件透传;空态无滚动容器不触发) |
669
+
670
+ | Slot | 说明 |
671
+ | --- | --- |
672
+ | empty | 覆盖空态整区 |
673
+ | welcome-name / welcome-description / welcome-icon | 单独配置欢迎页主标题/描述/吉祥物(转发 Welcome 同名插槽) |
674
+ | welcome-suggestions | 单独配置欢迎页建议区(整体替换默认 Prompts 快捷条) |
675
+ | scroll-button | 自定义滚到底部悬浮按钮整块(作用域 { scrollToBottom, awayFromBottom };覆盖后内置按钮与显隐逻辑均由插槽内容接管) |
676
+ | scroll-button-icon | 仅自定义悬浮按钮图标内容(按钮本体/显隐不变) |
677
+ | message-avatar / message-actions | 透传给每条 AiMessage(message-avatar 优先于细分头像插槽) |
678
+ | user-avatar / assistant-avatar | 自定义用户/助手头像(assistant-avatar 作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于同名 props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
679
+ | user-name / assistant-name | 自定义用户/助手名称(作用域 { message },优先于同名 props) |
680
+
681
+ | CSS 变量 | 默认 | 说明 |
682
+ | --- | --- | --- |
683
+ | --fv-messages-max-width | none | 滚动内容最大宽度;超出部分左右居中(内层 `.fv-messages-inner`,配合 `margin: 0 auto`) |
684
+ | --fv-messages-top-gap | 22px | 消息区滚动容器顶部留白:首条消息距顶部的间距,不贴顶;空态不生效(无滚动容器) |
685
+ | --fv-messages-bottom-gap | 72px | 消息区滚动容器底部留白:滚到底时最后一条消息距底部的间距,不贴输入区(sender);空态不生效(无滚动容器) |
686
+
687
+ | Ref | 说明 |
688
+ | --- | --- |
689
+ | scrollTo(options) | 滚动到指定位置(options 同原生 ScrollToOptions,也可传 number) |
690
+ | scrollToBottom(smooth?) / scrollToTop() | 滚动控制 |
691
+ | expandThoughtChains() / collapseThoughtChains() | 全部展开/折叠当前链上消息的思考链 |
692
+
693
+ ### AiMessage
694
+
695
+ 单条消息(Markdown 正文 + 思考链折叠 + 附件 + 操作区)。
696
+
697
+ | Prop | 类型 | 默认 | 说明 |
698
+ | --- | --- | --- | --- |
699
+ | message | MessageNode | (必填) | 消息节点 |
700
+ | branch | AiMessageBranchInfo | undefined | 分支元数据 { count, index };缺省视为单分支 |
701
+ | isLast | boolean | false | 是否当前链最后一条消息(由 AiMessages 注入)。**追问建议已不再限链尾**(历史消息同样渲染),本 prop 仅作透传兼容保留,不参与任何显隐判定 |
702
+ | showActions | boolean | true | 显示复制/重生成。assistant **待回答落定(status=done)才渲染**——生成中(pending/streaming)不出复制/重生成/评价等工具按钮;error 无正文也不出;user 仅有文案(content 非空)时才渲染复制按钮——纯附件无文字的消息复制的是一段空串,按钮无意义不出;分支切换器不受此门控 |
703
+ | showBranchSwitch | boolean | true | 显示分支切换器(branch.count > 1 时) |
704
+ | showUserAvatar | boolean | false | 显示用户头像(默认隐藏;false 时用户消息不渲染头像块) |
705
+ | showUserName | boolean | false | 显示用户名称(默认隐藏;false 时用户消息不渲染头部名称行) |
706
+ | showAssistantAvatar | boolean | true | 显示助手头像(false 时助手消息不渲染头像块) |
707
+ | showAssistantName | boolean | false | 显示助手名称(默认隐藏;false 时助手消息不渲染头部名称行) |
708
+ | userAvatar | string | '' | 用户头像图片 URL(空串回落内置图标) |
709
+ | assistantAvatar | string | '' | 助手头像图片 URL(传入完全覆盖不分状态;空串按状态回落内置 GIF:thinking=fvai-thinking.gif,done/error=fvai-idle.gif) |
710
+ | assistantAvatarScale | number | 1 | 助手头像缩放系数(默认 1 不缩放;CSS 变量 --fv-msg-avatar-scale 同效,prop 优先) |
711
+ | avatarCircle | boolean | true | 头像圆形模式(透传 AiMessage;默认 true:圆角 50%;--fv-msg-avatar-radius 变量优先于开关) |
712
+ | userName | string | '' | 用户名称(空串回落「你」) |
713
+ | assistantName | string | '' | 助手名称(空串回落「Gizmo」) |
714
+ | autoCollapse | boolean | true | 正文出完自动收起思考链(status 落 done 且正文打字机不再打字时折叠;error 不收,保留链供排查;历史消息不受影响,仍默认收起) |
715
+ | typing | boolean \| { step?; interval? } | false | 打字机(透传 Typewriter;仅 assistant 流式期间生效,落定/历史消息整段渲染) |
716
+ | collapsible | boolean | false | 思考链工具步长文案展开/收起开关(透传 ThoughtChain) |
717
+ | showDuration | boolean | false | 显示工具步用时 description(透传 ThoughtChain;默认关闭) |
718
+ | showTime | boolean | true | 显示消息时间(操作区按钮之后;时间源:message.createdTime(秒级/毫秒级时间戳或 ISO 字符串自动识别)优先,缺省回落 message.createdAt;两者皆无则不渲染。助手消息 SSE 生成中不显示,正文打完字(未启用打字机则落定)后才显示;error 即显;user 消息恒显示) |
719
+ | timeFormat | (message, timestamp) => string | undefined | 消息时间自定义格式化(透传消息与已归一为 ms 的时间戳;缺省 'YYYY-MM-DD HH:mm',本机时区) |
720
+ | codeTriggerLangs | string[] | — | 代码块「预览」触发语言(透传 Markdown/Typewriter;命中语言的代码块右上角注入按钮,点击行为由消费方事件委托实现) |
721
+ | followupStyle | 'list' \| 'chips' | 'list' | 追问建议展示样式:'list'(默认)纵向列表一行一条,渲染在操作区(工具栏)下方,顶部浅灰分隔线 + 「追问」标题(不加粗,与正文同色,字号随正文,经语言包 `aiMessage.followupsTitle` 自定义),条目 100% 宽、下划线分隔(浅灰,末条不出线)、字号随正文、文案次级灰;'chips' 旧横向气泡形态(换行铺排,无标题)。assistant 消息带 suggestions 即渲染——历史消息同样显示,不再限链尾;**正文打字效果完成后才渲染**(流式 suggestions 事件到达不显示,落定+打完字整体浮现) |
722
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子:渲染附件 url 前调用,返回可直渲地址(如 JWT fetch 换 blob objectURL);缺省原样使用 url(blob/dataURL/公开地址),远端地址解析结果按 url 缓存 + 在途去重,失败回落原 url |
723
+ | feedbackHandler | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR', comment?) => Promise\<unknown\> \| unknown | undefined | 消息评价提交钩子:仅 assistant 最终回答行(role=assistant 且 status=done,error/中断/生成中不渲染)渲染 👍/👎,缺省不渲染按钮。点击 👍 直接提交,点击 👎 弹**居中附言弹窗**(ElDialog,textarea ≤500 字 + 提交/跳过,点遮罩/ESC 关闭草稿保留、再点 👎 复填),再次点击当前态按钮发 CLEAR;乐观更新——先翻转 message.feedback 再调钩子,失败回滚并经 feedback-error 上抛,成功经 feedback-change 上抛;返回 resolved 即成功,返回错误文案串/抛错均视为失败。**弹窗标题/占位可自定义**(语言包 `aiMessage.feedback.dislikeTitle`/`dislikePlaceholder`;标题 `{name}` 占位渲染时替换为 assistantName,空串回落 defaultAssistantName) |
724
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
725
+
726
+ > 用户消息操作区:恒渲染复制按钮,默认透明,鼠标移上消息(或键盘聚焦)时浮现(open-webui 交互)。
727
+
728
+ | Event | 说明 |
729
+ | --- | --- |
730
+ | copy / regenerate / branch-change | (message) / (message) / (dir, message) |
731
+ | followup-select | (item, message) 点击追问建议(item 为建议文本;assistant 消息带 suggestions 即渲染——历史消息同样显示,不限链尾;**正文打字效果完成后才渲染**,落定后可点;AiChat 内部已接住转 send,直接用 AiMessage 时的消费方需自行接管发送) |
732
+ | file-click | (file, message) 点击附件:图片缩略图默认打开内置 ElImageViewer 放大(同消息多图轮播,url 经 resolveFileUrl 解析);文档附件渲染为 FilesCard 卡片(类型图标 + 名称/大小,复用输入区同款),卡片右上角 28px 下载按钮(hover 浮现)——点击内置触发浏览器下载(url 经 resolveFileUrl 解析),不触发本事件;点击卡片本体仅上抛本事件(无内置下载行为,宿主可埋点/接管) |
733
+ | feedback-change | (message, action: 'LIKE' \| 'DISLIKE' \| 'CLEAR') 评价提交成功(乐观落定后触发;message.feedback 已更新,宿主可埋点/联动) |
734
+ | feedback-error | (message: string) 评价提交失败(钩子 reject/返回错误文案;乐观更新已回滚,message 为错误文案) |
735
+ | typing | 打字机输出中(流式期间节奏性触发) |
736
+
737
+ | Slot | 说明 |
738
+ | --- | --- |
739
+ | message-avatar | 自定义头像(作用域 { message };优先于细分头像插槽,两条角色消息均生效) |
740
+ | user-avatar | 自定义用户头像(无作用域;优先于 userAvatar props) |
741
+ | assistant-avatar | 自定义助手头像(作用域 { status, message },status 为 thinking/done/error,可按状态换头像;优先于 assistantAvatar props;未传插槽且未传 assistantAvatar 时内置头像本身随状态切换) |
742
+ | user-name | 自定义用户名称(作用域 { message };优先于 userName props) |
743
+ | assistant-name | 自定义助手名称(作用域 { message };优先于 assistantName props) |
744
+ | message-files | 自定义附件渲染(作用域 { message, files };默认:图片缩略图按钮(点击内置放大预览),文档 FilesCard 卡片(类型图标 + 名称/大小,复用输入区同款,卡片右上 28px 下载按钮 hover 浮现可下载);user 消息只传附件无文字时不渲染空正文气泡) |
745
+ | message-actions | 自定义操作区(作用域 { message }) |
746
+
747
+ | Ref | 说明 |
748
+ | --- | --- |
749
+ | message | 当前消息节点(computed) |
750
+ | expandThoughtChain() / collapseThoughtChain() | 展开/折叠本条消息的思考链(user 消息、无思考链、单 item 平铺形态调用无效) |
751
+
752
+ ### AiArtifacts
753
+
754
+ Artifacts 预览面板(iframe 沙箱,从消息 ```html / ```svg 代码块提取)。
755
+
756
+ | Prop | 类型 | 默认 | 说明 |
757
+ | --- | --- | --- | --- |
758
+ | artifacts | AiArtifactItem[] | [] | artifact 列表 { key(必填), type: 'html'/'svg', content, title? } |
759
+ | activeKey | string | '' | 当前展示的 key;为空时面板隐藏 |
760
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en'/'ko'/'vi'/'zh-HK' 整包或部分文案对象(优先于祖先注入与全局设置) |
761
+
762
+ | Event | 说明 |
763
+ | --- | --- |
764
+ | close / change | 关闭 / 切换(key) |
765
+ | navigate | (href) iframe 内点击外链被拦截上抛 |
766
+
767
+ | Ref | 说明 |
768
+ | --- | --- |
769
+ | open(key) / close() | 程序化显隐 |
770
+
771
+ ### AiSessionSidebar
772
+
773
+ 可收起的会话侧栏(FvAiSessionSidebar):品牌行 + 新对话 + 未归档/已归档 tab + 搜索 + 会话列表。新建仅切草稿态(DRAFT_SESSION_ID 哨兵,不发 service.create);列表触底分页加载;菜单内置重命名/删除(确认弹窗)与归档/恢复(service.archive 未实现时自动隐藏)。通常与 FvAiChatPanel 并排使用,由宿主编排(选中会话 → 传 Panel 的 sessionId;session-created/round-complete → 调 refresh 刷列表)。
774
+
775
+ ```vue
776
+ <script setup lang="ts">
777
+ import { ref } from 'vue'
778
+ import { FvAiSessionSidebar, DRAFT_SESSION_ID } from '@fv-ui/ai-chat'
779
+ import type { FvAiSessionService } from '@fv-ui/ai-chat'
780
+
781
+ const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
782
+ const activeId = ref(DRAFT_SESSION_ID)
783
+ const collapsed = ref(false)
784
+ const sidebarRef = ref()
785
+ </script>
786
+
787
+ <template>
788
+ <FvAiSessionSidebar
789
+ ref="sidebarRef"
790
+ :service="service"
791
+ :active-id="activeId"
792
+ v-model:collapsed="collapsed"
793
+ @select="(id) => (activeId = id)"
794
+ @new-chat="() => (activeId = DRAFT_SESSION_ID)"
795
+ @removed="(id) => id === activeId && (activeId = DRAFT_SESSION_ID)"
796
+ />
797
+ </template>
798
+ ```
799
+
800
+ | Prop | 类型 | 默认 | 说明 |
801
+ | --- | --- | --- | --- |
802
+ | service | FvAiSessionService | (必填) | 会话数据服务(宿主注入;archive 可选,未实现时隐藏归档 tab 与菜单项) |
803
+ | activeId | string | (必填) | 当前会话 id(草稿哨兵 DRAFT_SESSION_ID 或真实 id) |
804
+ | v-model:collapsed | boolean | false | 收起态(默认展开);收起态窄条竖排「展开 + 新建 + 搜索」三个图标按钮 |
805
+ | pageSize | number | 20 | 列表分页大小 |
806
+ | searchable | boolean | true | 显示搜索框(后端标题模糊匹配,输入防抖 400ms,清空即恢复) |
807
+ | brandName | string | 'Gizmo' | 品牌名称 |
808
+ | brandIcon | string | 内置品牌头像 | 品牌徽章图片 URL(默认内置 fvai_avatar_256.webp) |
809
+ | locale | LocaleInput(string \| 对象) | undefined | 语言包:'zh-CN'/'en-US' 整包或部分文案对象(优先于祖先注入与全局设置) |
810
+
811
+ | Event | 说明 |
812
+ | --- | --- |
813
+ | update:collapsed | 收起/展开同步(v-model:collapsed) |
814
+ | select | (sessionId, status?: 'ACTIVE' \| 'ARCHIVED') 选中会话切换;新建时载荷为 DRAFT_SESSION_ID(status 供父层记录会话状态) |
815
+ | new-chat | 点了「新对话」(无论此前是否已在草稿态;父层用于草稿态重播欢迎动画) |
816
+ | removed | (sessionId) 删除了当前会话(父层需切走) |
817
+
818
+ | Slot | 说明 |
819
+ | --- | --- |
820
+ | brand | 覆盖品牌行整行(徽章 + 名称 + 折叠按钮) |
821
+ | new-chat | 覆盖「新对话」按钮内容(按钮元素保留,点击行为不变) |
822
+ | menu | 覆盖会话行 hover 菜单项(作用域 { item };默认重命名/归档/删除) |
823
+ | item | 覆盖会话行内容(作用域 { item, active }) |
824
+
825
+ | Ref | 说明 |
826
+ | --- | --- |
827
+ | refresh() | 静默刷新列表(不打 loading 遮罩;供父层在懒创建落库/首轮回复完成后调,刷新标题/活跃时间) |
828
+ | reload() | 重载首页列表(与内部首载同路径) |
829
+
830
+ ### AiChatPanel
831
+
832
+ 对话面板(FvAiChatPanel,无头设计:会话状态/标题由侧栏表达,面板只承担对话):内嵌 FvAiChat + 会话历史加载 + 草稿懒创建。「加载更早」按钮悬浮消息区顶部(仅已拉详情且贴顶时出现),按 seq 游标向前翻页合并。
833
+
834
+ ```vue
835
+ <script setup lang="ts">
836
+ import { ref } from 'vue'
837
+ import { ElMessage } from 'element-plus'
838
+ import { FvAiChatPanel, FvCommonAdapter, DRAFT_SESSION_ID } from '@fv-ui/ai-chat'
839
+ import type { FvAiSessionService } from '@fv-ui/ai-chat'
840
+
841
+ const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
842
+ const adapter = FvCommonAdapter({ baseURL: '/api', sessionId: () => sessionId.value })
843
+ const sessionId = ref<string>(DRAFT_SESSION_ID)
844
+ const panelRef = ref()
845
+ </script>
846
+
847
+ <template>
848
+ <FvAiChatPanel
849
+ ref="panelRef"
850
+ :service="service"
851
+ :adapter="adapter"
852
+ :session-id="sessionId"
853
+ style="height: 600px"
854
+ @session-created="(id) => (sessionId = id)"
855
+ @error="(err) => ElMessage.error(err.message)"
856
+ />
857
+ </template>
858
+ ```
859
+
860
+ Props 按用途分四组:
861
+
862
+ **数据**(会话/聊天接入):
863
+
864
+ | Prop | 类型 | 默认 | 说明 |
865
+ | --- | --- | --- | --- |
866
+ | service | FvAiSessionService | (必填) | 会话数据服务(list/rename/remove 面板不消费,接口完整传入) |
867
+ | adapter | ChatAdapter | (必填) | 聊天适配器(草稿懒创建由面板包装层承担) |
868
+ | sessionId | string | (必填) | 当前会话 id(草稿哨兵或真实 id) |
869
+ | detailLimit | number | 100 | 首屏 detail 条数 |
870
+ | historyLimit | number | 50 | 「加载更早」每次拉取条数 |
871
+
872
+ **展示**(透传 FvAiChat):
873
+
874
+ | Prop | 类型 | 默认 | 说明 |
875
+ | --- | --- | --- | --- |
876
+ | welcomeLayout | 'horizontal' \| 'vertical' | 'horizontal' | 空态欢迎页布局(悬浮窗等窄宽场景用 vertical) |
877
+ | centerWelcome | boolean | true | 空态欢迎内容垂直居中(悬浮窗等窄高场景传 false:欢迎页贴上、输入区贴底,透传 FvAiChat centerWelcome) |
878
+ | placeholder | string | '' | 输入框占位 |
879
+ | suggestions | AiChatSuggestion[] | [] | 空态建议列表(建议池属宿主业务,库内不做抽样) |
880
+ | suggestionsTitle | string | '' | 空态建议标题 |
881
+ | suggestionsWrap | boolean | true | 空态建议换行模式 |
882
+ | typing | boolean \| { step?; interval? } | true | 打字机 |
883
+ | collapsible | boolean | true | 思考链长文案展开/收起开关 |
884
+ | showTime | boolean | true | 显示消息时间 |
885
+ | theme | 'light' \| 'dark' \| 'auto' | 'light' | 主题 |
886
+ | locale | LocaleInput | undefined | 语言配置(透传 FvAiChat + 面板自身文案) |
887
+ | toolStepLabel | (toolName: string) => string | undefined | 工具名 → 步骤展示名 |
888
+
889
+ **功能**(附件/评价钩子,透传 FvAiChat;草稿态懒创建由面板包装层承担):
890
+
891
+ | Prop | 类型 | 默认 | 说明 |
892
+ | --- | --- | --- | --- |
893
+ | allowAttachments | boolean | false | 开启输入区附件上传 |
894
+ | accept | string | '' | 附件 input accept 属性 |
895
+ | attachmentLimit | number | 0 | 附件数量上限 |
896
+ | uploadAttachment | (file, item) => ... | undefined | 附件上传钩子(语义同 AiChat) |
897
+ | resolveFileUrl | (file: ChatFile) => Promise\<string\> \| string | undefined | 附件地址解析钩子 |
898
+ | feedbackHandler | FeedbackHandler | undefined | 消息评价提交钩子 |
899
+
900
+ **布局**(限宽,CSS 变量注入):
901
+
902
+ | Prop | 类型 | 默认 | 说明 |
903
+ | --- | --- | --- | --- |
904
+ | messagesMaxWidth | string | '1160px' | 消息区限宽 |
905
+ | senderMaxWidth | string | '1200px' | 输入区限宽(非草稿态) |
906
+ | draftSenderMaxWidth | string | '780px' | 草稿态输入区限宽(聚焦欢迎页视觉中心) |
907
+
908
+ | Event | 说明 |
909
+ | --- | --- |
910
+ | session-created | (sessionId) 草稿首条消息懒创建成功(父层换真实 id;本组件守卫跳过重载) |
911
+ | round-complete | 一轮回复完成(父层延时刷新会话列表标题/活跃时间) |
912
+ | error | (err) 生成/懒创建失败(错误上抛,toast 留给宿主) |
913
+ | message-complete / attachment-exceed / attachment-uploaded / message-file-click / feedback-change / feedback-error | FvAiChat 事件透传(载荷语义同 AiChat) |
914
+
915
+ | Slot | 说明 |
916
+ | --- | --- |
917
+ | empty / welcome-name / welcome-description / welcome-icon / welcome-suggestions | FvAiChat 空态插槽透传 |
918
+ | user-avatar / assistant-avatar / user-name / assistant-name / message-avatar / message-actions | FvAiChat 消息插槽透传(作用域同 AiChat) |
919
+ | sender-prefix | 输入区前缀(转发 FvAiChat #prefix) |
920
+
921
+ | Ref | 说明 |
922
+ | --- | --- |
923
+ | replayWelcome() | 重播欢迎页(草稿态下重复点「新对话」sessionId 不变,父层经此方法让整框重建、动画从头跑一遍;非草稿态 no-op) |
924
+ | loadEarlier() | 手动触发「加载更早」(与按钮同路径;无更早消息/草稿态/加载中 no-op) |
925
+ | refresh() | 直通刷新:对当前会话重新拉 detail 并重建视图(草稿态 no-op) |
926
+
927
+ ### AiChatWidget
928
+
929
+ 悬浮对话面板(FvAiChatWidget):Teleport 到 body,双形态——`drawer` 抽屉(默认:贴 position 侧全屏高,`offsetTop`/`offsetBottom` 各自留白)/ `floating` 悬窗(独立窗口,高度默认视口高 - 上下留白 - 80,可拖 header 自由移动,整窗限视口内不出界);宽度可经拖拽手柄调整(`minWidth`~`maxWidth`,默认 450~640px;抽屉仅内缘一个手柄,悬窗左右两缘均可调,拖左缘时窗口同步平移、右缘不动),拖拽落定经 localStorage 记忆(`storageKey` 自定义)。头部左侧「头像 + AI 名称」(默认内置品牌头像),右侧图标按钮均带 tooltip:「历史会话 + 新对话 + 模式切换 + 最大化 + 关闭」;点历史会话图标在对话区覆盖式下拉(层挂在 body 内,header 露出不遮挡;顶部「返回」工具条收层,内嵌 FvConversations:「今天/以往」分组 + hover 菜单重命名/删除 + 触底分页,打开即拉取,点行切会话);主体内嵌 FvAiChatPanel(常规态 welcomeLayout 固定 vertical、centerWelcome 固定 false 窄宽形态:欢迎页贴上、输入区贴底,建议列表为 FAQ 式行列表——行间细分隔线、行尾箭头指示、hover 底色对称淡入淡出)。**最大化**(`maximizable`,默认 true;关闭按钮左侧按钮,亦经 `toggleMaximize()` 编程式切换):inset 0 占满视口的覆盖态,退出后回到进入前的 drawer/floating 原形态;最大化态头部收敛(头像/标题/历史/新对话/模式切换隐藏,标识由侧栏品牌行承担,仅留还原/关闭;关闭面板即退出最大化,再开回常规形态),FvAiSessionSidebar 升为根级全高覆盖(选中/新建/删除/搜索/归档全能力,service/locale/品牌透传;默认收起为 44px 悬浮窄条、可展开 260px,对话区经 padding-left 让位/收回),Panel 欢迎页转横排 + 垂直居中,限宽三参回库默认 1160/1200/780px 聚焦中栏,建议列表转大屏胶囊横排;拖拽/调宽/头部按钮随态禁用。面板底带主色角部微光渐变(科技感,亮暗两态;暗色下透明度升档 + 边框调亮 + 投影加深,面板与同色系页面背景可分层)。会话编排收在内部:草稿哨兵起步、session-created 换真实 id 并刷历史列表、round-complete 延时 2.5s 刷列表。**关闭保活**(`keepAlive`,默认 true):关闭仅隐藏(v-show),实例/对话树原样保留,再开不重渲染、不重拉历史。
930
+
931
+ ```vue
932
+ <script setup lang="ts">
933
+ import { ref } from 'vue'
934
+ import { FvAiChatWidget, FvAiChatLauncher, FvCommonAdapter } from '@fv-ui/ai-chat'
935
+ import type { FvAiSessionService } from '@fv-ui/ai-chat'
936
+
937
+ const service: FvAiSessionService = { /* 宿主胶水,见下节 */ } as FvAiSessionService
938
+ const adapter = FvCommonAdapter({ baseURL: '/api' })
939
+ const open = ref(false) // 两个 v-model 接同一 ref
940
+ </script>
941
+
942
+ <template>
943
+ <FvAiChatLauncher v-model="open" position="right" />
944
+ <FvAiChatWidget
945
+ v-model="open"
946
+ :service="service"
947
+ :adapter="adapter"
948
+ title="AI 助手"
949
+ position="right"
950
+ />
951
+ </template>
952
+ ```
953
+
954
+ | Prop | 类型 | 默认 | 说明 |
955
+ | --- | --- | --- | --- |
956
+ | modelValue | boolean(v-model) | false | 显隐 |
957
+ | width | string | '450px' | 面板宽度(css 值;拖拽调宽在其上生效) |
958
+ | minWidth / maxWidth | number | 450 / 640 | 拖拽调宽下/上界(px) |
959
+ | position | 'right' \| 'left' | 'right' | 贴靠侧(滑入方向随侧;抽屉拖拽手柄在内侧对缘,悬窗两缘均可调宽) |
960
+ | offsetTop | number | 0 | 面板距屏幕上边缘留白(px) |
961
+ | offsetBottom | number | 0 | 面板距屏幕下边缘留白(px) |
962
+ | mode | 'drawer' \| 'floating' | 'drawer' | 面板形态:抽屉(贴侧全屏高,拖 header 超 100px 转悬窗并就地接管)/ 悬窗(独立定高,可拖 header 移动;拖到左/右视口缘持续 0.5s 出抽屉吸附预览,松开即吸附为对应侧抽屉并同步内部贴靠侧) |
963
+ | floatingHeight | string | ''(视口高 - 上下留白 - 80) | 悬窗模式高度(css 值;drawer 模式忽略) |
964
+ | storageKey | string | 'fv-ai-chat-widget' | 宽度记忆 storage key:以 `!` 结尾视为完整 key,否则作前缀拼 `-width`;空串禁用记忆 |
965
+ | keepAlive | boolean | true | 关闭保活:关闭仅隐藏(v-show),实例/对话树原样保留,再开不重渲染、不重拉历史;设 false 则关闭即销毁(v-if),每次打开重建 |
966
+ | maximizable | boolean | true | 支持最大化:头部显示最大化按钮(关闭按钮左侧);最大化占满视口、头部头像/标题/历史/新对话/模式按钮收敛(标识由侧栏品牌行承担),FvAiSessionSidebar 升为根级全高覆盖(盖住 header 左列,logo 不重复),欢迎页转大屏横排 |
967
+ | title | string | '' | 头部标题(空时回落 locale AI 名称) |
968
+ | avatar | string | 内置品牌头像 | 头部头像图片 URL |
969
+ | service | FvAiSessionService | (必填) | 会话数据服务(透传 Panel 与 Sidebar) |
970
+ | adapter | ChatAdapter | (必填) | 聊天适配器(透传 Panel) |
971
+ | sessionId | string | '' | 当前会话 id(缺省内部 DRAFT 编排;传入则受控优先) |
972
+ | placeholder / suggestions / suggestionsTitle / suggestionsWrap / typing / collapsible / showTime / theme / locale / toolStepLabel | | | FvAiChatPanel 同名 props 透传 |
973
+ | allowAttachments / accept / attachmentLimit / uploadAttachment / resolveFileUrl / feedbackHandler | | | FvAiChatPanel 附件/评价钩子透传 |
974
+ | detailLimit / historyLimit | number | 100 / 50 | 首屏 detail / 「加载更早」每次条数(透传 Panel) |
975
+
976
+ 注:Panel 的 `welcomeLayout` 在 Widget 内常规态固定为 `vertical`、`centerWelcome` 固定为 `false`(欢迎页贴上、输入区贴底),限宽三参(messagesMaxWidth 等)固定为 `'none'`,均不透传;最大化态自动切为 `horizontal` + 居中 + 限宽回库默认;消息头像经 `--fv-msg-avatar-size` 固定 38px(库默认 50px)。
977
+
978
+ | Event | 说明 |
979
+ | --- | --- |
980
+ | update:modelValue | 显隐同步 |
981
+ | open / close | 面板打开 / 关闭(受控 modelValue 由 false→true / true→false 时上抛) |
982
+ | session-change | (sessionId) 内部会话切换(选中会话/新对话/删除切草稿/回退上一次对话;宿主可选监听对账) |
983
+ | session-created / round-complete / error / message-complete / attachment-exceed / attachment-uploaded / message-file-click / feedback-change / feedback-error | FvAiChatPanel 事件透传(载荷语义同 AiChatPanel) |
984
+
985
+ | Slot | 说明 |
986
+ | --- | --- |
987
+ | header-avatar / header-title / header-actions | Widget 头部:替换头像 / 替换标题 / 在标题与默认按钮之间追加自定义按钮(交互可配合 `newChat()`/`switchToPrevious()`) |
988
+ | empty / welcome-name / welcome-description / welcome-icon / welcome-suggestions | 原样转发 FvAiChatPanel 空态插槽 |
989
+ | user-avatar / assistant-avatar / user-name / assistant-name / message-avatar / message-actions / sender-prefix | 原样转发 FvAiChatPanel 消息/输入区插槽(作用域同 AiChatPanel) |
990
+
991
+ | Ref | 说明 |
992
+ | --- | --- | --- |
993
+ | open() / close() | 编程式开合(与 v-model 等价) |
994
+ | toggleMode() | 编程式切换 drawer/floating 形态(与头部模式按钮等价) |
995
+ | toggleMaximize() | 编程式切换最大化(与头部最大化按钮等价:最大化 ⇄ 还原为进入前形态) |
996
+ | newChat() | 新建对话(与头部「新对话」按钮等价:切草稿;已在草稿则重播欢迎页) |
997
+ | switchToPrevious() | 切回上一次对话(来路栈回退,浏览器后退式;栈空回落历史列表首条真实会话);返回 `boolean` 表示是否切换成功 |
998
+ | refresh() | 刷新当前会话(透传 Panel.refresh:重新拉 detail 并重建视图;草稿态 no-op) |
999
+
1000
+ ### AiChatLauncher
1001
+
1002
+ 悬浮入口按钮(FvAiChatLauncher):**blob 光晕**(内嵌 [FvBlobHalo](#fvblobhalo) 基础组件:主题色 + AI 紫 + 浅紫 + 白色四色色团,`d: path()` 变形 + 异速旋转,全部居中叠放混色;光晕约 1.6 倍按钮径。暗色下紫系压暗、白层变黑层;无白色图标底,头像直接铺满圆心)。与 FvAiChatWidget 组合时宿主把两个 v-model 接到同一 ref;亦可独立控任意目标。双形态:`floating`(默认)贴角悬浮;`floating: false` 文档流内联,可嵌进顶栏/卡片/按钮组;`interactive: false` 渲染为非交互 `<span>`(光晕照常动),可作纯展示图标引用。中间图标优先级:`#icon` 插槽 > `iconComponent` 组件 > `icon` 图片 URL > 内置品牌头像;`halo` 对象整体透传内嵌 FvBlobHalo(色板/缩放/透明度/转速/暂停)。
1003
+
1004
+ ```vue
1005
+ <FvAiChatLauncher v-model="open" placement="bottom-right" :size="48" />
1006
+
1007
+ <!-- 内联非交互小图标(顶栏引用) -->
1008
+ <FvAiChatLauncher :interactive="false" :floating="false" :size="32" />
1009
+
1010
+ <!-- 光晕调参 -->
1011
+ <FvAiChatLauncher v-model="open" :halo="{ colors: ['#ff8c42', '#fcaf58', '#f9c784', '#fff'], rotateDuration: 15 }" />
1012
+ ```
1013
+
1014
+ | Prop | 类型 | 默认 | 说明 |
1015
+ | --- | --- | --- | --- |
1016
+ | modelValue | boolean(v-model) | false | 按钮激活态(面板开时按钮高亮,仅视觉;点击 emit click + update:modelValue 取反;interactive=false 时不渲染激活态) |
1017
+ | floating | boolean | true | 是否悬浮贴角;false 时文档流内联(placement/offset 失效),可嵌进顶栏/卡片/按钮组 |
1018
+ | interactive | boolean | true | 是否可交互;false 时渲染 `<span>`,无点击/hover/aria,光晕照常动,作纯展示图标引用 |
1019
+ | placement | 'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' | 'bottom-right' | 悬浮四角定位(floating 时生效) |
1020
+ | position | 'right' \| 'left' | | **废弃**(兼容保留):未传 placement 时按 `bottom-{position}` 推导;与 placement 同传以 placement 为准(dev 警告) |
1021
+ | offsetX / offsetY | number | 回落 offset | 距角横/纵轴留白(px,分轴设置) |
1022
+ | offset | number | 24 | 距角双轴统一留白(px 简写;offsetX/offsetY 优先) |
1023
+ | size | number | 38 | 按钮直径(px) |
1024
+ | ariaLabel | string | '' | 无障碍标签(空时回落 locale `aiChatPanel.launcher`;interactive 时生效) |
1025
+ | icon | string | '' | 默认图标图片 URL(缺省内置品牌头像;iconComponent/#icon 插槽优先) |
1026
+ | iconComponent | Component | | 组件形态图标(与 icon 冲突时优先;#icon 插槽仍最高) |
1027
+ | halo | FvAiChatLauncherHalo | | 光晕属性整体透传内嵌 FvBlobHalo:{ colors?, scale?, opacity?, altOpacity?, rotateDuration?, paused? };覆盖 Launcher 内置默认(scale 1.6 / opacity .1 / altOpacity .35) |
1028
+ | locale | LocaleInput | undefined | 语言包 |
1029
+
1030
+ | Event | 说明 |
1031
+ | --- | --- |
1032
+ | update:modelValue | 点击后激活态取反 |
1033
+ | click | (MouseEvent) 原生点击 |
1034
+
1035
+ | Slot | 说明 |
1036
+ | --- | --- |
1037
+ | default | 整体替换按钮内容(光晕层恒在,内容铺在光晕之上;存在时 #icon 不渲染) |
1038
+ | icon | 覆盖按钮图标(默认内置品牌头像图,圆形裁切铺满) |
1039
+
1040
+ ### FvAiSessionService(会话数据服务)
1041
+
1042
+ 会话数据服务接口:宿主实现后经 prop 注入 FvAiSessionSidebar / FvAiChatPanel / FvAiChatWidget。库内不内置网络实现;错误提示(toast)由宿主胶水层统一承担(库对 service 失败:侧栏静默、面板空态重建)。
1043
+
1044
+ ```ts
1045
+ import { DRAFT_SESSION_ID } from '@fv-ui/ai-chat'
1046
+ import type { FvAiSessionService, FvAiSessionPage, FvAiMessagePage } from '@fv-ui/ai-chat'
1047
+
1048
+ /** 草稿会话哨兵:进入模块/新建/删除当前会话即切草稿态,不调 service.create;
1049
+ * 首条消息发出时由 FvAiChatPanel 懒创建 service.create 后上抛 session-created 换真实 id */
1050
+ DRAFT_SESSION_ID // '__draft__'
1051
+
1052
+ interface FvAiSessionService {
1053
+ /** 会话列表(分页,updatedTime DESC;status 筛选与 keyword 搜索正交同传) */
1054
+ list(q: { pageNum: number; pageSize: number; status?: 'ACTIVE' | 'ARCHIVED'; keyword?: string }): Promise<FvAiSessionPage>
1055
+ /** 新建会话,返回新会话 id */
1056
+ create(): Promise<string>
1057
+ /** 会话详情消息(尾部 limit 条,seq 升序) */
1058
+ detail(sessionId: string, limit?: number): Promise<FvCommonMessage[]>
1059
+ /** 加载更早消息(beforeSeq 游标) */
1060
+ history(sessionId: string, beforeSeq: number, limit?: number): Promise<FvAiMessagePage>
1061
+ /** 重命名 */
1062
+ rename(args: { sessionId: string; title: string }): Promise<void>
1063
+ /** 删除 */
1064
+ remove(sessionId: string): Promise<void>
1065
+ /** 归档/恢复(可选;未实现时侧栏隐藏归档 tab 与菜单项) */
1066
+ archive?(args: { sessionId: string; archived: boolean }): Promise<void>
1067
+ }
1068
+
1069
+ // 归一化形状(宿主 IPage 格式由胶水转换)
1070
+ interface FvAiSessionPage { items: FvCommonSessionItem[]; hasMore: boolean }
1071
+ interface FvAiMessagePage { messages: FvCommonMessage[]; hasMore: boolean }
1072
+ ```
1073
+
1074
+ 宿主胶水示例(det-oms 风格:list/create/detail/history/rename/remove 转发到宿主 httpRequest,并把后端 IPage 归一化为 { items, hasMore };**错误 toast 由胶水层承担**):
1075
+
1076
+ ```ts
1077
+ import { ElMessage } from 'element-plus'
1078
+ import type { FvAiSessionService } from '@fv-ui/ai-chat'
1079
+
1080
+ /** 宿主统一请求封装(JSON 返回;非 2xx/业务错误码直接 reject) */
1081
+ declare function httpRequest<T>(url: string, data?: unknown): Promise<T>
1082
+
1083
+ export const sessionService: FvAiSessionService = {
1084
+ async list(q) {
1085
+ const page = await httpRequest('/ai-chat/session/list', q) // IPage<T>
1086
+ return { items: page.records, hasMore: page.current * page.size < page.total }
1087
+ },
1088
+ create: () => httpRequest<{ id: string }>('/ai-chat/session/create').then((r) => r.id),
1089
+ detail: (sessionId, limit = 100) =>
1090
+ httpRequest('/ai-chat/session/detail', { sessionId, limit }),
1091
+ history: async (sessionId, beforeSeq, limit = 50) => {
1092
+ const page = await httpRequest('/ai-chat/session/history', { sessionId, beforeSeq, limit })
1093
+ return { messages: page.records, hasMore: page.records.length >= limit }
1094
+ },
1095
+ rename: (args) => httpRequest('/ai-chat/session/rename', args),
1096
+ remove: (sessionId) => httpRequest('/ai-chat/session/remove', { sessionId })
1097
+ }
1098
+
1099
+ // 错误 toast:胶水层统一承担(库对 service 失败静默)
1100
+ // httpRequest 内部 catch → ElMessage.error(后端 message 文案)后 reject
1101
+ ```
1102
+
1103
+ ### mapHistoryToNodes / sessionToConversationItem(历史回放映射)
1104
+
1105
+ `src/core/historyMapper.ts` 导出的两个纯映射函数(Fv 系后端消息行 → MessageNode 树 / FvConversations 项),独立使用时的签名:
1106
+
1107
+ ```ts
1108
+ import { mapHistoryToNodes, sessionToConversationItem, type AiChatT } from '@fv-ui/ai-chat'
1109
+
1110
+ /** 后端消息行(seq 升序)→ MessageNode 树(历史回放状态机):
1111
+ * user 行 → user 节点;assistant 中间轮 + tool 结果行按 toolCallId 配对
1112
+ * 累积进本轮最终 assistant 的 toolSteps;GENERATING → 「回复生成中断」灰条;
1113
+ * FAILED/INTERRUPTED → error 态;附件/评价/追问建议一并还原 */
1114
+ function mapHistoryToNodes(messages: FvCommonMessage[], t?: AiChatT): MessageNode[]
1115
+
1116
+ /** 会话列表项 → FvConversations item(key=id;group 仅作归档兜底分组,
1117
+ * 展示分组由消费方按「今天/以往」覆写) */
1118
+ function sessionToConversationItem(s: FvCommonSessionItem, t?: AiChatT): {
1119
+ key: string; label: string; group?: string; disabled?: boolean
1120
+ }
1121
+ ```
1122
+
1123
+ `t` 参数为翻译函数(`(key: string, named?: Record<string, string>) => string`,vue-i18n t 的结构子类型):文案 key 为库 locale `historyMapper` 分组的中文原文(如「回复生成中断」「用时 {s}」);**缺省回落库内 locale**(传入组件 locale 即随语言切换,无需自己拼 t)。带 `named` 占位参数时做 `{name}` 简单插值,未知占位符原样保留。
1124
+
1125
+ FvAiChatPanel 内部已按上述口径注入 t 后调用;仅独立使用该函数时需要关心。
1126
+
1127
+ ### 人工验证点(文档站)
1128
+
1129
+ - 历史会话下拉覆盖层(Widget 头部时钟图标:仅遮对话区不遮 header、返回按钮收层、分组列表、打开即拉取、点行切会话)
1130
+ - 炫光动画帧率(Launcher conic 旋转 + 光晕 breathing,低端机不掉帧)
1131
+ - 窄宽欢迎页布局(Widget 内 welcomeLayout=vertical,输入区/建议条不溢出)
1132
+ - 暗色主题下面板与按钮观感(theme=dark 下 Widget/Launcher 颜色对比)
1133
+
1134
+ ## Composables
1135
+
1136
+ ### useChat(options)
1137
+
1138
+ 聊天编排:发送 → 流式回填 → 队列/重生成/续写。
1139
+
1140
+ ```ts
1141
+ import { useChat, zhCN, en, ko, vi, zhHK } from '@fv-ui/ai-chat' // 内置语言包(可换成自建包)
1142
+
1143
+ const lang = ref<'zh-CN' | 'en' | 'ko' | 'vi' | 'zh-HK'>('zh-CN')
1144
+
1145
+ const LOCALES = { 'zh-CN': zhCN, en, ko, vi, 'zh-HK': zhHK }
1146
+
1147
+ const chat = useChat({
1148
+ adapter: () => OpenAIAdapter({ baseURL, apiKey }), // 实例或工厂;工厂每次 send 惰性取用
1149
+ models: () => selectedModels.value, // 数组或工厂;多模型并行生成兄弟分支
1150
+ initial: { messages, currentId }, // 恢复会话
1151
+ onToolEvent: (ev) => { /* Fv 系通用 tool{status},展示「正在查询库存…」*/ },
1152
+ // 语言包工厂:返回 LocaleMessages 包对象(内置包或自建包),非语言名字符串
1153
+ locale: () => LOCALES[lang.value]
1154
+ })
1155
+ // chat: { send, stop, regenerate, continueGenerate, enqueue, queue, isLoading,
1156
+ // msgs, messages, currentId, chain }
1157
+ ```
1158
+
1159
+ - `send(text, files?)`:生成中调用被拒;多模型时各模型一个 assistant 节点并发回填
1160
+ - `stop()`:中止全部在途请求,在途节点置 done(保留半截内容)
1161
+ - `regenerate(messageId?)`:回退焦点到父节点重发生成新分支(旧回答保留)
1162
+ - `continueGenerate(messageId?)`:以既有内容为前缀续写,增量追加到同一节点
1163
+ - `enqueue(text, files?)`:生成中入队,完成后自动 flush 队首
1164
+ - `onToolEvent`:适配器 `onTool` 回调的透传挂点(如 FvCommonAdapter 的 tool{status} 事件)
1165
+ - `locale`:语言包工厂 `() => LocaleMessages`,惰性取用(与 adapter/models 工厂同语义);影响附件 system prompt、工具用时、续写 prompt 等发给后端的文案,缺省读全局设置,见[国际化](#国际化i18n)
1166
+
1167
+ ### FvCommonAdapter(config)
1168
+
1169
+ Fv 系后端通用聊天适配器(`/api/ai-chat/*`):六事件 SSE 协议(`message_start` / `tool` / `delta` / `reasoning` / `message_end` / `error`),POST `/ai-chat/message/send`。适用于 Fv 各项目组返回此结构的后端。会话管理(列表/归档/删除等)由消费方直接调后端,不经此适配器。
1170
+
1171
+ ```ts
1172
+ const adapter = FvCommonAdapter({
1173
+ baseURL: '/api', // 或 https://host
1174
+ headers: () => ({ Authorization: 'Bearer ' + token }), // 惰性取用
1175
+ sessionId: () => currentSessionId.value, // 工厂:切换会话后下一次 send 生效
1176
+ errorMessages: { 90602: '已有进行中的对话' } // 业务码 → 文案映射(可选)
1177
+ })
1178
+ ```
1179
+
1180
+ - 同步段失败(Content-Type 非 `text/event-stream`)按 JSON 错误 `{code,message}` 走 `onError`;命中 `errorMessages` 时用映射文案(带 `code` 的 `FvCommonError`)
1181
+ - `message_end` 的 `messageId`(最终文本行 id)经 `onBackendMessageId` 回填到 `MessageNode.backendId`——多轮工具循环下与 `message_start` 的首轮 id 不同,UI 落库/对账以它为准
1182
+ - `tool` 事件经 `onTool` → `useChat.onToolEvent` → `AiChat @tool-event` 上抛,消费方展示「正在查询库存…」等中间态
1183
+ - 追问建议(V58+):`suggestions` 事件(流式收尾 0..1 次,最后一个 delta 后、message_end 前,载荷 `{items: string[]}`)经可选 `onSuggestions` 上抛,`useChat` 回写 `MessageNode.suggestions`,AiMessage 对带 suggestions 的 assistant 消息渲染追问(默认纵向列表样式——顶部灰色分隔线 + 加粗「追问」标题、条目 100% 宽下划线分隔字号随正文,`followupStyle='chips'` 切回横向气泡;**正文打字效果完成后才渲染**,流式事件到达不显示,历史消息同样渲染,不再限链尾);开关关闭/模型未产出/中断/失败无此事件;历史恢复用导出的 `parseSuggestions(raw)` 安全解析 `FvCommonMessage.suggestions`(JSON 数组原文透传,脏数据按无建议)
1184
+ - 消息评价(V58+):`FvCommonMessage.feedback`(LIKE/DISLIKE,未评价/旧数据恒 null)、`feedbackComment`(附言 ≤500 字)、`feedbackTime`(评价落库时间)三字段同款容错;历史恢复由消费方映射为 `MessageNode.feedback` 灌入展示;评价提交走独立端点(POST /message/feedback),不经本适配器——接 `AiChat` 的 `feedbackHandler` 钩子即可
1185
+ - 附件快照(1.4.1+):user 行 `FvCommonMessage.attachments`(id/originalName/type/suffix/sizeBytes/downloadUrl,旧数据/无附件恒 null),历史回放映射 `MessageNode.files` 渲染(图片缩略图 + 文档 FilesCard 卡片,卡片右上 28px 下载按钮 hover 浮现可下载;downloadUrl 需鉴权取流时配 `resolveFileUrl` 钩子,下载/预览均走解析后地址)
1186
+ - 配套 DTO 类型:`FvCommonSessionItem` / `FvCommonMessage` / `FvCommonSessionDetail` / `FvCommonMessagePage`(消费方直接调会话管理端点时用)
1187
+
1188
+ ### useMessages(initial?)
1189
+
1190
+ 树形消息状态中枢(响应式包装 `createMessageTree`)。
1191
+
1192
+ 返回:`messages`(全量节点表)、`currentId`、`chain`(当前链 computed)、`add`、`remove`、`edit`、`appendContent`、`navigate(id?, dir?)`、`setCurrent(id)`、`setStorage(adapter)`、`load()`、`flush()`、`toJSON()`。绑定存储后树变更自动去抖(150ms)落盘。
1193
+
1194
+ ### useXStream()
1195
+
1196
+ SSE 流消费:`startStream({ readableStream, transformStream? })`、`cancel()`、`data: Ref<SSEEvent[]>`、`error`、`isLoading`。内部完成 `\r\n`/跨 chunk 边界归一化。
1197
+
1198
+ ### useSend() / XRequest
1199
+
1200
+ `useSend()`:`send({ url, method?, headers?, body?, transformStream?, onChunk? })`(SSE data 为 JSON 且含 content 字段时逐块回调)、`abort()`、`loading`、`error`。在飞行守卫:上一个 send 未结束时新 send 被忽略。
1201
+
1202
+ `XRequest(url, options)`:Promise 化,resolve 累计全文。
1203
+
1204
+ ### useRecord()
1205
+
1206
+ 语音录制 + 实时转写:`start()` / `stop()` / `isRecording` / `text` / `audioUrl` / `error`。SpeechRecognition 不可用时降级为仅录音。
1207
+
1208
+ ## 自定义 ChatAdapter
1209
+
1210
+ 实现 `ChatAdapter` 接口即可接入任意后端(自研网关、Ollama、非 OpenAI 协议):
1211
+
1212
+ ```ts
1213
+ import type { ChatAdapter } from '@fv-ui/ai-chat'
1214
+
1215
+ const myAdapter: ChatAdapter = {
1216
+ async send(req, handlers) {
1217
+ // req: { messages: [{ role, content }], model?, stream?, signal? }
1218
+ try {
1219
+ const res = await fetch('/api/chat', {
1220
+ method: 'POST',
1221
+ headers: { 'content-type': 'application/json' },
1222
+ body: JSON.stringify(req),
1223
+ signal: req.signal
1224
+ })
1225
+ if (!res.ok) { handlers.onError(new Error(`HTTP ${res.status}`)); return }
1226
+ // 流式:自行逐块解析,回调增量
1227
+ handlers.onDelta('一段正文')
1228
+ handlers.onReasoning('一段思考链') // 可选
1229
+ handlers.onUsage({ prompt_tokens: 10, completion_tokens: 20 }) // 可选
1230
+ handlers.onDone() // 正常结束必须调用
1231
+ } catch (e) {
1232
+ if (req.signal?.aborted) return // 主动中止不算错误
1233
+ handlers.onError(e instanceof Error ? e : new Error(String(e)))
1234
+ }
1235
+ },
1236
+ abort() {
1237
+ // 中止全部在途请求
1238
+ }
1239
+ }
1240
+
1241
+ // 用法
1242
+ <FvAiChat title="AI" :adapter="myAdapter" />
1243
+ ```
1244
+
1245
+ 一次 `send` 对应一次完整生成:持续回调 `onDelta` 增量,最后必须 `onDone()` 或 `onError()`;`stop()` 时组件会调 `abort()`。
1246
+
1247
+ 持久化可选 `StorageAdapter`(`get/set/remove`,async),内置 `createLocalStorageAdapter()`(localStorage 不可用时自动降级内存)与 `createMemoryAdapter()`;经 `useMessages().setStorage()` 绑定。
1248
+
1249
+ ## 主题定制
1250
+
1251
+ 组件样式基于 Element Plus CSS 变量,覆盖 EP 变量即完成主题定制:
1252
+
1253
+ ```scss
1254
+ // 全局或局部覆盖(需在引入 dist/style.css 之后)
1255
+ :root {
1256
+ --el-color-primary: #7c3aed;
1257
+ }
1258
+ ```
1259
+
1260
+ 高级定制可直接 `@use` 源 SCSS 入口:
1261
+
1262
+ ```scss
1263
+ @use '@fv-ui/ai-chat/src/styles/index.scss' with (
1264
+ // scss 变量(若组件有定义)
1265
+ );
1266
+ ```
1267
+
1268
+ > 源码 SCSS 入口仅供源码依赖场景;npm 消费方推荐使用构建产物 `dist/style.css` + CSS 变量覆盖。
1269
+
1270
+ ## 国际化(i18n)
1271
+
1272
+ 内置五份语言包:`zh-CN`(默认,零配置)、`en`、`ko`、`vi`、`zh-HK`;所有组件文案(按钮 aria/tooltip、状态文案、MessageBox、错误提示、发给模型的续写 prompt)均从语言包读取。
1273
+
1274
+ ### 全局设置(推荐)
1275
+
1276
+ ```ts
1277
+ import { configureLocale } from '@fv-ui/ai-chat'
1278
+
1279
+ configureLocale('en') // 整库切英文;configureLocale('zh-CN') 切回,可选 'ko'/'vi'/'zh-HK'
1280
+ ```
1281
+
1282
+ ### 组件级 prop
1283
+
1284
+ 每个含文案的组件都有 `locale` prop,两种形态:
1285
+
1286
+ ```vue
1287
+ <!-- 整包切换(优先级最高) -->
1288
+ <FvAiChat locale="en" ... />
1289
+
1290
+ <!-- 部分覆盖:在当前生效语言上深合并,只改指定文案 -->
1291
+ <FvAiChat :locale="{ aiMessage: { regenerate: '重答' }, sender: { send: 'GO' } }" ... />
1292
+ ```
1293
+
1294
+ 解析优先级:**组件 prop > 祖先 `<FvAiChat>` 注入 > 全局设置**。`<FvAiChat>` 会把解析结果注入整框后代(Sender/消息区/Artifacts 等),后代组件的 `locale` prop 仍可局部覆盖;单独使用基础组件(FvSender/FvConversations...)时 prop 缺省则读全局。
1295
+
1296
+ ### 自建完整语言包
1297
+
1298
+ ```ts
1299
+ import { configureLocale, zhCN, type LocaleMessages } from '@fv-ui/ai-chat'
1300
+
1301
+ const jaJP: LocaleMessages = {
1302
+ ...zhCN,
1303
+ common: { ...zhCN.common, send: '送信', copy: 'コピー' },
1304
+ aiMessage: { ...zhCN.aiMessage, defaultAssistantName: 'アシスタント' }
1305
+ // 未覆盖的 key 自动回落 zh-CN 值;建议展开全部 key 覆盖
1306
+ }
1307
+ configureLocale(jaJP)
1308
+ ```
1309
+
1310
+ `configureLocale` 的对象形态是**完整语言包**(定基准);组件 `locale` prop 的对象形态是**部分覆盖**(在基准上微调),两者语义有意不同。
1311
+
1312
+ ### 语言包 key 一览
1313
+
1314
+ 下表列出 zh-CN 与 en 两列对照;`ko`/`vi`/`zh-HK` 词条与之一一同构,详见语言包源文件 `src/locale/{ko,vi,zh-HK}.ts`。
1315
+
1316
+ | 分组 | key | zh-CN | en |
1317
+ | --- | --- | --- | --- |
1318
+ | common | copy / delete / confirm / cancel / retry / close / preview / clear / stop / send / download / fullscreen / collapse / expand | 复制 / 删除 / 确定 / 取消 / 重传 / 关闭 / 预览 / 清空 / 停止 / 发送 / 下载 / 全屏 / 收起 / 展开 | Copy / Delete / OK / Cancel / Retry / Close / Preview / Clear / Stop / Send / Download / Fullscreen / Collapse / Expand |
1319
+ | thinking | start / thinking / end / interrupted / error / endWithTools / interruptedWithTools / thinkingItem / thoughtDoneItem | 开始思考 / 思考中... / 思考完成 / 思考中断 / 思考遇到问题 / 思考完成,使用 {n} 个工具 / 思考中断,使用 {n} 个工具 / 正在思考 / 思考完成 | Thinking / Thinking... / Thought complete / Thought interrupted / Something went wrong / Thought complete, used {n} tools / Thought interrupted, used {n} tools / Thinking / Thought complete |
1320
+ | welcome | greetingPrefix / greetingName / description | 你好,我是 ␣ / Gizmo / 我可以帮你查询数据、分析问题、生成报表、以及执行系统操作,让生产管理更高效。 | Hello, I am ␣ / Gizmo / I can help you query data, analyze problems, generate reports, and perform system operations... |
1321
+ | sender | clear / stop / send / speech / recordCancel / recordConfirm / micUnavailable / inputPlaceholder | 清空 / 停止 / 发送 / 语音输入 / 取消录音 / 确认录音 / 无法访问麦克风 / 输入你的问题,查询数据、分析问题或生成报表… | Clear / Stop / Send / Voice input / Cancel recording / Confirm recording / Microphone unavailable / Ask a question — query data, analyze problems, or generate reports… |
1322
+ | editorSender | clear / stop / send / inputPlaceholder / selectTagTitle / loading / tagTip | 清空 / 停止 / 发送 / 请输入 / 选择标签 / 加载中… / 填写内容后回车确认 | Clear / Stop / Send / Type something... / Select a tag / Loading... / Type and press Enter to confirm |
1323
+ | attachments | add / retry / uploading | 添加附件 / 重传 / 上传中… | Add attachment / Retry / Uploading… |
1324
+ | filesCard | remove | 删除 | Remove |
1325
+ | conversations | menuLabel / rename / delete / renameTitle / renamePrompt / renamePlaceholder / deleteTitle / deleteConfirm | 会话操作 / 重命名 / 删除 / 重命名会话 / 请输入新的会话名称 / 请输入名称 / 删除会话 / 确定删除会话「{label}」吗?... | Conversation actions / Rename / Delete / Rename conversation / Enter a new conversation name / Enter a name / Delete conversation / Delete "{label}"? ... |
1326
+ | scroll | toBottom | 滚动到底部 | Scroll to bottom |
1327
+ | aiChat | modelPlaceholder / adapterMissing / generateFailed / exportUser / exportAssistant | 模型 / 未配置 adapter 或 baseURL / 生成失败 / 你 / 助手 | Model / Neither adapter nor baseURL is configured / Generation failed / You / Assistant |
1328
+ | aiMessage | copy / regenerate / prevBranch / nextBranch / defaultUserName / defaultAssistantName / querying / queried / generateFailed / followups / followupsTitle / loadingPhrases / feedback.{like, dislike, dislikeTitle, dislikePlaceholder, submit, skip, failed, cleared} | 复制 / 重新生成 / 上一分支 / 下一分支 / 你 / Gizmo / 正在查询 / 已查询 / 生成失败 / 追问建议 / 追问 / [正在思考…, 正在整理思路…, 正在生成回答…] / 点赞 / 点踩 / 抱歉,请告诉 {name} 哪里不好 / 欢迎说说你的想法 / 提交 / 跳过 / 评价提交失败 / 已取消评价 | Copy / Regenerate / Previous branch / Next branch / You / Gizmo / Querying / Queried / Generation failed / Follow-up suggestions / Follow-ups / [Thinking..., Organizing thoughts..., Generating your answer...] / Like / Dislike / Sorry — tell {name} what went wrong / Feel free to share your thoughts / Submit / Skip / Failed to submit feedback / Feedback removed |
1329
+ | aiArtifacts | copy / download / fullscreen / close | 复制 / 下载 / 全屏 / 关闭 | Copy / Download / Fullscreen / Close |
1330
+ | chat | fileTag / fileImageTag / filesSystemPrompt / toolDuration / continuePrompt | [附件] {name} / (图片) / 用户随消息提供了以下文件:\n{files} / 用时 {s} / 请基于以上内容继续完成回答... | [File] {name} / ␣(image) / The user provided... / Took {s} / Continue completing... |
1331
+ | errors | requestFailed / sessionIdMissing / noBody / generateFailed / recordUnsupported / speechError / attachmentRejected | 请求失败 / 缺少 sessionId(...) / 响应无 body / 生成失败 / 当前环境不支持音频录制 / 语音识别错误: {error} / 不支持该类型文件,禁止上传:{name} | Request failed / sessionId is missing... / Response has no body / Generation failed / Audio recording... / Speech recognition error: {error} / This file type is not supported: {name} |
1332
+
1333
+ 占位符 `{label}`/`{name}`/`{files}`/`{s}`/`{n}`/`{error}` 由组件在渲染/构造时替换。`querying`/`queried` 与工具名拼接时由组件显式补一个空格(显示为「正在查询 xxx」),词条本身不含尾随空格,覆盖时无需保留间距。`welcome.greetingPrefix` 保留尾随空格(与 greetingName 直接拼接,高亮 span 交界处)。`aiMessage.loadingPhrases` 为生成中占位的轮换文案数组(进入占位立即显示第一条,此后每 3s 轮换循环);覆盖时数组**整体替换**(deepMerge 不合并数组叶子),传空数组则只显示 spinner 无文案。`aiMessage.feedback.dislikeTitle` 中的 `{name}` 由组件渲染点踩附言弹窗时替换为 `assistantName`(空串回落 `defaultAssistantName`),如需静态标题请直接传完整文案。
1334
+
1335
+ ### 与 vue-i18n 共存
1336
+
1337
+ 本库不依赖 vue-i18n。若项目已在用,把 LocaleMessages 挂进 vue-i18n messages 后引用其值传 prop 即可桥接:
1338
+
1339
+ ```vue
1340
+ <FvAiChat :locale="$tm('fvAiChat')" /> <!-- $tm 返回 fvAiChat 节点的对象作为语言包传入 -->
1341
+ ```
1342
+
1343
+ ### 已落库数据不回溯
1344
+
1345
+ 语言切换只影响之后的渲染与请求;已写入消息树的工具用时(`用时 1.2s`)、历史 error 文案保持产生时的语言。
1346
+
1347
+ ## 暗色模式
1348
+
1349
+ `<FvAiChat theme="dark">` 或 `theme="auto"`(跟随 `prefers-color-scheme`):组件向 `<html>` 注入/移除 `dark` class,配合 element-plus 的暗色变量生效:
1350
+
1351
+ ```ts
1352
+ // main.ts 引入 EP 暗色变量
1353
+ import 'element-plus/theme-chalk/dark/css-vars.css'
1354
+ ```
1355
+
1356
+ ```vue
1357
+ <FvAiChat theme="auto" ... />
1358
+ ```
1359
+
1360
+ 注意:组件卸载时会移除 `html.dark`(单实例假设);多实例并用暗色需自行管理 class。
1361
+
1362
+ ## Prism 主题引入
1363
+
1364
+ 代码高亮默认配色由组件样式提供;要换成其他 Prism 主题,在 `dist/style.css` 之后引入覆盖:
1365
+
1366
+ ```ts
1367
+ import '@fv-ui/ai-chat/dist/style.css'
1368
+ import '@fv-ui/ai-chat/styles/prism-tomorrow.min.css'
1369
+ ```
1370
+
1371
+ 内置主题:`prism`(默认)、`prism-coy`、`prism-dark`、`prism-funky`、`prism-okaidia`、`prism-solarizedlight`、`prism-tomorrow`、`prism-twilight`。
1372
+
1373
+ ## FAQ
1374
+
1375
+ **Q:页面是白屏/样式错乱?**
1376
+ A:确认已引入 `element-plus/dist/index.css` 与 `@fv-ui/ai-chat/dist/style.css`,且 `app.use(ElementPlus)`。
1377
+
1378
+ **Q:`<FvAiChat>` 发送报"未配置 adapter 或 baseURL"?**
1379
+ A:`adapter` 与 `baseURL` 至少传一个。
1380
+
1381
+ **Q:外层改了 `v-model:messages` 为什么界面没变?**
1382
+ A:半受控语义:外部 messages 只在初始灌入一次,后续界面变化全量上抛 `update:messages`,请经 v-model 回写而不是直接改源数组。
1383
+
1384
+ **Q:多模型怎么用?**
1385
+ A:`<FvAiChat model="a" :models="['a', 'b']">` 顶栏出现多选,选中的多个模型并行生成,回答互为分支可切换。
1386
+
1387
+ **Q:`features` 里的 tts/queue/continueGenerate/fullscreenEditor?**
1388
+ A:接口已预留,当前版本仅 `artifacts` 生效,其余待后续版本接线。
1389
+
1390
+ **Q:KaTeX 公式没渲染?**
1391
+ A:FvMarkdown 内置 `@vscode/markdown-it-katex`,确认公式语法正确即可;无需额外引入。
1392
+
1393
+ **Q:Vite dev 下内置头像/欢迎页 GIF 不显示(404 破图)?**
1394
+ A:Vite dev 的依赖预打包(esbuild)不复制 `new URL(..., import.meta.url)` 引用的资产(vitejs/vite#8427)。在 `vite.config.ts` 加 `optimizeDeps: { exclude: ['@fv-ui/ai-chat'] }`,详见[「Vite 项目必读」](#vite-项目必读排除依赖预打包)。
1395
+
1396
+ **Q:Nuxt/SSR 环境首渲染报错 "DOMPurify 不可用:当前环境无 window"?**
1397
+ A:FvMarkdown 依赖浏览器 `window`(DOMPurify 消毒),不支持服务端首渲染。Nuxt 下请用 `<ClientOnly>` 包裹(或客户端挂载后再渲染):
1398
+
1399
+ ```vue
1400
+ <ClientOnly>
1401
+ <FvAiChat ... />
1402
+ </ClientOnly>
1403
+ ```
1404
+
1405
+ ## 已知限制与 Roadmap
1406
+
1407
+ 以下能力数据层已就绪,组合 UI 待后续版本接线(v0.2 计划):
1408
+
1409
+ - **消息列表懒加载**:`useMessages` 数据面支持分页注入,`AiMessages` 暂全量渲染;超长对话建议自行分页。
1410
+ - **消息操作条**:当前内置复制/重新生成;编辑/删除/继续生成/朗读请经 `useChat`(`editMessage`/`removeMessage`/`continueGenerate`)或 `#message-actions` 插槽自建入口。
1411
+ - **队列卡片**:`useChat.enqueue` 可用,`features.queue` 展示 UI 待接线。
1412
+ - **语音输入**:`Sender` 的 `allowSpeech` 依赖浏览器 `SpeechRecognition`(Chrome/Edge 可用,Firefox 不支持转写,降级为仅录音、确认后无文本);录音/波形需要 HTTPS 或 localhost 环境。
1413
+ - **多实例暗色互斥**:`theme` 采用单写者假设,多实例同屏请自行管理 `html.dark`。
1414
+
1415
+ ## 类型与导出
1416
+
1417
+ 包入口导出全部组件(含会话应用层 `FvAiSessionSidebar`/`FvAiChatPanel`/`FvAiChatWidget`/`FvAiChatLauncher`、氛围光基础组件 `FvBlobHalo`)、`useChat`/`useMessages`/`useXStream`/`useSend`/`XRequest`/`useRecord`、`OpenAIAdapter`、`FvCommonAdapter`(+ `FvCommonError` 及配套 DTO 类型)、`parseSuggestions`(追问建议 JSON 安全解析)、`createMessageTree`、`createLocalStorageAdapter`/`createMemoryAdapter`、`createSSEParser`、`configureLocale`/`zhCN`/`en`/`ko`/`vi`/`zhHK`(国际化)、会话数据层 `DRAFT_SESSION_ID`/`FvAiSessionService`(及 `FvAiSessionListQuery`/`FvAiSessionPage`/`FvAiMessagePage`)、历史回放映射 `mapHistoryToNodes`/`sessionToConversationItem`(+ `AiChatT`)及全部公共类型(`MessageNode`、`ChatAdapter`、`ChatFile`、`MessageFeedback`、`FeedbackHandler`、`MessageUsage`、`SSEEvent`、`LocaleMessages`、`LocaleCode`、`LocaleInput`、`DeepPartialLocale` 等),消费方:
1418
+
1419
+ ```ts
1420
+ import { FvAiChat, OpenAIAdapter, useChat } from '@fv-ui/ai-chat'
1421
+ import type { MessageNode, ChatAdapter } from '@fv-ui/ai-chat'
1422
+ ```