BrutxUI

简体中文

English

简体中文

English

外观

ChatBubble 聊天气泡 ​

支持三种消息角色变体的聊天 UI 组件，粗边框气泡 + 阴影偏移让对话界面充满个性张力。

预览 ​

Preview
对话开始于 2025-06-01
AL
Alex
嘿！这个新粗野主义 UI 库看起来太赞了！
14:01
我
我
对吧！粗边框 + 硬朗阴影，直接把普通组件卷死。
14:02
AL
Alex
Kanban + TreeView 这两个复合组件是重头戏 🔥
14:03
我
我
还有 Carousel！Embla 驱动的，性能拉满 💪
14:03

颜色（仅 sent 生效）

AL
Alex
received 不受 color 影响
14:00
我
我
default 配色
14:01
我
我
primary 配色
14:02
我
我
accent 配色
14:03

尺寸

我
我
sm 小号气泡
14:00
我
我
default 默认气泡
14:01
我
我
lg 大号气泡
14:02

安装 ​

pnpm dlx brutx-vue@latest add chat-bubble

用法 ​

vue
<script setup>
import { ChatBubble } from 'brutx-ui-vue'

const message = {
    id: '1',
    variant: 'received',
    name: 'Alex',
    content: '这个 UI 库太好用了！',
    timestamp: '14:01',
}
</script>

<template>
    <div class="flex flex-col gap-3">
        <ChatBubble :message="{ id: '1', variant: 'received', name: 'Alex', content: '你好！' }" />
        <ChatBubble :message="{ id: '2', variant: 'sent', content: '嘿！' }" />
        <ChatBubble :message="{ id: '3', variant: 'system', content: '对话已开始' }" />
    </div>
</template>

颜色变体 ​

color 属性用于为 variant="sent" 的气泡切换背景配色，与 variant 正交组合（如 variant="sent" color="accent"）。received 与 system 气泡不受 color 影响。

vue
<script setup>
import { ChatBubble } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex flex-col gap-3">
        <ChatBubble :message="{ id: '1', variant: 'sent', content: '默认配色', timestamp: '14:00' }" color="default" />
        <ChatBubble :message="{ id: '2', variant: 'sent', content: '主色配色', timestamp: '14:01' }" color="primary" />
        <ChatBubble :message="{ id: '3', variant: 'sent', content: '强调色配色', timestamp: '14:02' }" color="accent" />
    </div>
</template>

变体 ​

消息角色 ​

变体样式用途
received左对齐，背景色对方消息
sent右对齐，主色背景自己发送的消息
system居中，斜体，虚线边框，无阴影，强制 text-xs系统通知

注意： system 变体会忽略 size prop，始终使用 text-xs；同时隐藏头像和发送者名称。

颜色 ​

颜色说明
default默认配色，sent 气泡使用主色（brutal-primary）背景
primary主色配色，sent 气泡使用主色（brutal-primary）背景，并附加主色阴影（shadow-brutal-primary）
accent强调色配色，sent 气泡使用强调色（brutal-accent）背景

尺寸 ​

size 属性同时控制气泡的内边距、文字大小以及头像尺寸。

尺寸气泡内边距文字大小头像尺寸
smpx-3 py-1.5text-xsw-6 h-6
defaultpx-4 py-2.5text-smw-8 h-8
lgpx-5 py-3.5text-basew-10 h-10
vue
<script setup>
import { ChatBubble } from 'brutx-ui-vue'
</script>

<template>
    <div class="flex flex-col gap-3">
        <ChatBubble :message="{ id: '1', variant: 'sent', name: '我', content: '小号气泡', timestamp: '14:00' }" size="sm" />
        <ChatBubble :message="{ id: '2', variant: 'sent', name: '我', content: '默认气泡', timestamp: '14:01' }" size="default" />
        <ChatBubble :message="{ id: '3', variant: 'sent', name: '我', content: '大号气泡', timestamp: '14:02' }" size="lg" />
    </div>
</template>

子组件 ​

ChatContainer 聊天容器 ​

支持时间分组的聊天消息容器：

vue
<script setup>
import { ChatContainer } from 'brutx-ui-vue'

const messages = [
    { id: '1', variant: 'received', name: 'Alex', content: '你好！', timestamp: new Date() },
    { id: '2', variant: 'sent', content: '嘿！', timestamp: new Date(), status: 'read' },
]
</script>

<template>
    <ChatContainer :messages="messages" group-by-time show-status />
</template>

数据类型 ​

ChatMessage ​

ts
interface ChatMessage {
    id: string                        // 消息唯一标识（必填）
    content: string                   // 消息文本内容（必填）
    variant?: 'sent' | 'received' | 'system'  // 消息变体，默认 'received'
    avatar?: string                   // 头像图片 URL，加载失败时回退为首字母缩写
    name?: string                     // 发送者姓名，用于显示名称和生成首字母缩写
    timestamp?: string | Date         // 时间戳，字符串直接展示，Date 对象按 dateFormat 或 toLocaleString 格式化
    status?: MessageStatus            // 消息状态，仅对 variant="sent" 有效
}

MessageStatus ​

ts
type MessageStatus = 'sending' | 'sent' | 'delivered' | 'read' | 'failed'
状态图标样式
sending旋转加载图标半透明 + 旋转动画
sent单勾半透明
delivered双勾略深
read双勾主题主色
failed警告图标销毁色

注意： status 在类型层面为上述闭联合类型，但消息数据通常来自后端 API，运行时可能拿到枚举之外的未知值；此时 ChatBubble 会静默忽略该状态（不显示状态图标），不会抛出错误。

API 参考 ​

ChatBubble

ChatBubble — 属性
名称类型默认值说明
message
必填
ChatMessage
—
要展示的聊天消息对象，包含 id、content、角色、时间戳以及可选头像和状态信息。
详情

声明类型

ChatMessage

关联类型

ChatMessage
类型定义 — ChatMessage
export interface ChatMessage {
    id: string
    content: string
    /** 消息角色，默认 'received' */
    variant?: 'sent' | 'received' | 'system'
    /** 头像图片 URL；加载失败时回退为首字母缩写 */
    avatar?: string
    /** 发送者姓名，用于展示名称与生成首字母缩写 */
    name?: string
    /**
     * 时间戳。
     * - `string`：按原样直接展示（不做格式化，传入方负责提供展示格式）；
     * - `Date`：按 `dateFormat` 或 `toLocaleString` 格式化。
     */
    timestamp?: string | Date
    /**
     * 消息状态，**仅对 `variant === 'sent'` 生效**；received/system 携带时会被静默忽略。
     */
    status?: MessageStatus
}

默认值详情

未声明默认值
—

来源

ChatBubble.vue:12

packages/ui/src/components/chat-bubble/ChatBubble.vue

color
"accent" | "default" | "primary" | undefined
"default"
设置 sent 角色气泡的配色；received 和 system 角色不受此属性影响。
详情

声明类型

NonNullable<"default" | "primary" | "accent" | null | undefined> | undefined

字面量

  • "accent"
  • "default"
  • "primary"

默认值详情

声明
'default'

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
"default"

来源

ChatBubble.vue:14

packages/ui/src/components/chat-bubble/ChatBubble.vue

size
"default" | "lg" | "sm" | undefined
"default"
设置气泡内边距和文字尺寸，并同步调整头像尺寸。
详情

声明类型

NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined

字面量

  • "default"
  • "lg"
  • "sm"

默认值详情

声明
'default'

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
"default"

来源

ChatBubble.vue:15

packages/ui/src/components/chat-bubble/ChatBubble.vue

showAvatar
boolean | undefined
true
控制头像区域的显示；system 角色始终不显示头像。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
true

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
true

来源

ChatBubble.vue:16

packages/ui/src/components/chat-bubble/ChatBubble.vue

showStatus
boolean | undefined
true
控制发送状态图标的显示；状态图标只用于 sent 角色。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
true

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
true

来源

ChatBubble.vue:17

packages/ui/src/components/chat-bubble/ChatBubble.vue

showTimestamp
boolean | undefined
true
控制消息时间戳的显示。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
true

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
true

来源

ChatBubble.vue:18

packages/ui/src/components/chat-bubble/ChatBubble.vue

dateFormat
((date: Date) => string) | undefined
undefined
自定义消息日期和时间的格式化函数；未提供时使用 Date.toLocaleString。
详情

声明类型

((date: Date) => string) | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
undefined

来源

ChatBubble.vue:19

packages/ui/src/components/chat-bubble/ChatBubble.vue

class
string | undefined
undefined
追加到消息气泡根元素的自定义 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/chat-bubble/ChatBubble.vue

解析值
undefined

来源

ChatBubble.vue:20

packages/ui/src/components/chat-bubble/ChatBubble.vue

ChatBubble — 插槽
名称签名或类型说明
#default
{}
替换消息主体内容；未提供时显示 message.content。
详情

声明类型

{}

来源

ChatBubble.vue

packages/ui/src/components/chat-bubble/ChatBubble.vue

ChatContainer

ChatContainer — 属性
名称类型默认值说明
messages
必填
ChatMessage[]
—
按顺序展示的聊天消息数组。
详情

声明类型

ChatMessage[]

关联类型

ChatMessage
类型定义 — ChatMessage
export interface ChatMessage {
    id: string
    content: string
    /** 消息角色，默认 'received' */
    variant?: 'sent' | 'received' | 'system'
    /** 头像图片 URL；加载失败时回退为首字母缩写 */
    avatar?: string
    /** 发送者姓名，用于展示名称与生成首字母缩写 */
    name?: string
    /**
     * 时间戳。
     * - `string`：按原样直接展示（不做格式化，传入方负责提供展示格式）；
     * - `Date`：按 `dateFormat` 或 `toLocaleString` 格式化。
     */
    timestamp?: string | Date
    /**
     * 消息状态，**仅对 `variant === 'sent'` 生效**；received/system 携带时会被静默忽略。
     */
    status?: MessageStatus
}

默认值详情

未声明默认值
—

来源

ChatContainer.vue:18

packages/ui/src/components/chat-bubble/ChatContainer.vue

groupByTime
boolean | undefined
false
启用按真实日历日期和时间间隔对消息分组，并显示日期或时刻分隔标签。
  • 有效时间戳按升序排序；缺失或无法解析的时间戳消息保留在输入数组对应位置和相对顺序。
  • 日期边界按真实年月日判断，不依赖 dateFormat 的输出；同一天内相邻消息间隔超过 groupInterval 分钟时另起时间分组。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
false

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
false

来源

ChatContainer.vue:19

packages/ui/src/components/chat-bubble/ChatContainer.vue

groupInterval
number | undefined
5
同一日期内相邻消息允许归入同一时间组的最大间隔，单位为分钟；小于 1 的值按 1 分钟处理。
详情

声明类型

number | undefined

默认值详情

声明
5

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
5

来源

ChatContainer.vue:20

packages/ui/src/components/chat-bubble/ChatContainer.vue

showAvatar
boolean | undefined
true
控制各条消息头像区域的显示。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
true

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
true

来源

ChatContainer.vue:21

packages/ui/src/components/chat-bubble/ChatContainer.vue

showStatus
boolean | undefined
true
控制 sent 消息状态图标的显示。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
true

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
true

来源

ChatContainer.vue:22

packages/ui/src/components/chat-bubble/ChatContainer.vue

showTimestamp
boolean | undefined
true
控制各条消息时间戳的显示。
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
true

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
true

来源

ChatContainer.vue:23

packages/ui/src/components/chat-bubble/ChatContainer.vue

dateFormat
((date: Date) => string) | undefined
undefined
格式化消息时间和分组标签的函数；未提供时使用本地日期时间格式。
详情

声明类型

((date: Date) => string) | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
undefined

来源

ChatContainer.vue:24

packages/ui/src/components/chat-bubble/ChatContainer.vue

class
string | undefined
undefined
追加到聊天容器根元素的自定义 CSS 类。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/chat-bubble/ChatContainer.vue

解析值
undefined

来源

ChatContainer.vue:25

packages/ui/src/components/chat-bubble/ChatContainer.vue

注意： 当 groupByTime 为 true 时：

  • 带有效时间戳的消息按时间升序排序，乱序输入也能得到连续、不跳变的日期分组；缺失或无法解析出有效时间戳的消息（如 '14:30'、'昨天' 等展示型字符串）按原索引锚定在原始位置，不沉底、相对顺序不变；
  • 分组边界基于真实日历日期（年/月/日）比较，与 dateFormat 的展示字符串解耦：即使自定义格式只输出时间维度（如 HH:mm），跨日期的消息也不会被误合并、同日期的消息也不会被拆成多个日期组；
  • 分组之间显示分隔线和日期标签（今天/昨天/具体日期）；
  • 同一日期内相邻消息时间差超过 groupInterval 分钟时，进一步拆分为独立分组，并展示具体时刻（HH:mm，可用 dateFormat 自定义），不重复日期标签。

可访问性 ​

  • ARIA 属性：ChatContainer 使用 role="log" 以支持无障碍访问
  • 语义化：消息气泡使用语义化结构，支持屏幕阅读器正确朗读

蛮力铸就。

© 2026 BrutxUI · MIT License