MateChat 组件大全与主题定制
一、组件概览
MateChat 的组件可以按“页面结构-消息渲染-交互输入-辅助扩展”四层来理解：
| 层 | 代表组件 | 作用 | 典型 Props / Slot |
|---|---|---|---|
| 布局层 | McLayout, McHeader, McLayoutContent, McLayoutSender | 搭出「顶栏-内容-输入栏」三段式骨架 | title, logoImg, slot operationArea 等 |
| 会话层 | McBubble, McList, McMarkDown | 把模型 / 用户输出以气泡、列表或富文本卡片形式呈现 | content, align, avatarConfig, loading |
| 输入层 | McInput, McPrompt, McMention | 文本录入、快捷提问、@-引用 | maxLength, placeholder, @submitlist, direction, @itemClick 等 |
| 引导层 | McIntroduction | 欢迎 / 空态页 | logoImg, title, subTitle, description, align, background |
命名规律：所有组件均以 Mc 前缀开头（MateChat 缩写），便于与业务自有组件区分。
二、核心组件
1. Layout
用于对不同的模块进行排列布局
1.1. 引入
import { McLayoutAside, McLayoutContent, McLayoutHeader, McLayout, McLayoutSender } from '@matechat/core';1.2. 组件对象
- McLayoutMcLayoutContentMcLayoutSenderMcLayoutAsideMcLayoutHeader
提供「顶栏-内容-输入栏」三段式布局
Tips：McLayoutContent 自带 100% 高度，与 McLayoutSender 互不干涉，可放心让消息区滚动。
1.3. Demo
<template> <McLayout> <McLayoutHeader> <McHeader :logoImg="'/logo.svg'" :title="'MateChat'"></McHeader> </McLayoutHeader> <McLayoutContent style="margin: 16px 0;"> <McBubble content="Hello MateChat" align="right"></McBubble> <McBubble content="Hello, what can I do for you?"></McBubble> </McLayoutContent> <McLayoutSender> <McInput :value="inputValue" :maxLength="2000" showCount></McInput> </McLayoutSender> </McLayout></template><script setup>import { ref } from 'vue';const msg = ref('组件demo');const inputValue = ref('');</script>2. Bubble
用于承载对话内容的气泡组件
2.1. 引入
import { McBubble } from '@matechat/core';2.2. 参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| content | string | '' | 气泡显示内容 |
| loading | boolean | false | 是否显示 loading 态，显示 loading 时其他区域将不会显示 |
| align | BubbleAlign + 'left' + 'right' | 'left' | 气泡对齐方式 |
| avatarPosition | AvatarPosition + 'top' + 'side' | 'side' | 头像位置 |
| variant | BubbleVariant + 'filled' + 'none' + 'bordered' | 'filled' | 气泡样式 |
| avatarConfig | BubbleAvatar | -- | 头像配置 |
interface BubbleAvatar { name?: string; // 头像内显示的名字 gender?: 'male' | 'female'; // 根据性别头像背景色会有所不同 width?: number; // 头像宽度 height?: number; // 头像高度 isRound?: boolean; // 是否是圆形头像 imgSrc?: string; // 头像显示图片，imgSrc 优先级比 name 高 displayName?: string; // 头像旁显示的名字，该属性仅当头像位于气泡上方时生效，如果希望当头像位于侧边时生效，我们推荐你通过 top 插槽来放置相关信息}2.3. Demo
<template> <McBubble :content="'Hello MateChat'" :avatarConfig="{ imgSrc: '/logo.svg' }"> <template #top> <div class="bubble-top-area"> <span>MateChat</span> </div> </template> <template #bottom> <div class="bubble-bottom-area"> <i class="icon icon-copy-new"></i> <i class="icon icon-like"></i> <i class="icon icon-dislike"></i> </div> </template> </McBubble></template>3. Prompt
用于展示一组预定义的问题或建议
3.1. 引入
import { McPrompt } from '@matechat/core';3.2. 参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| direction | ListDirection + vertical + horizontal | 'vertical' | 排列方式，水平或垂直 |
| list | Prompt[] | [] | 提示列表 |
| variant | ListVariant + 'transparent' + 'filled' + 'bordered' + 'none' | 'filled' | 提示样式 |
interface Prompt { value: string | number; label: string; iconConfig?: IconConfig; desc?: string;}interface IconConfig { name: string; size?: string; color?: string; component?: Component; // 支持传入自定义 vue 组件}3.3. Demo
<template> <div class="demo-container"> <McPrompt :list="promptData"></McPrompt> <McPrompt :list="promptData" :direction="'horizontal'"></McPrompt> </div></template><script setup>const promptData = [ { value: 'quickSort', label: '帮我写一个快速排序', iconConfig: { name: 'icon-info-o', color: '#5e7ce0' }, desc: '使用 js 实现一个快速排序', }, { value: 'helpMd', label: '你可以帮我做些什么？', iconConfig: { name: 'icon-star', color: 'rgb(255, 215, 0)' }, desc: '了解当前大模型可以帮你做的事', },];</script><style scoped lang="scss">.demo-container { display: flex; flex-direction: column; gap: 8px;}</style>4. Input
用于对话的输入框组件
4.1. 引入
import { McInput } from '@matechat/core';4.2. 参数
| 参数名 | 类型 | 默认值 | 说明 | |
|---|---|---|---|---|
| value | string | '' | 输入框的值 | |
| placeholder | string | -- | 输入框占位文字 | |
| disabled | boolean | false | 是否禁用输入框 | |
| displayType | DisplayType + 'simple' + 'full' | 'full' | 输入框的形态 | |
| loading | boolean | false | 是否发送中，为 true 时，点击发送按钮可暂停回答 | |
| showCount | boolean | false | 是否显示字数统计 | |
| maxLength | number | -- | 输入框的最大字数 | |
| submitShortKey | SubmitShortKey ` | null` + 'shiftEnter' + 'enter' | 'enter' | 发送快捷键，null 表示不使用快捷键发送 |
| variant | InputVariant + 'bordered' + 'borderless' | 'bordered' | 输入框的形态 | |
| sendBtnVariant | SendBtnVariant + 'simple' + 'full' | 'full' | 发送按钮的形态 |
4.3. Demo
<template> <McInput :value="inputValue" :maxLength="2000" :loading="loading" showCount @change="onInputChange" @submit="onSubmit" @cancel="onCancel"> </McInput></template><script setup>import { defineComponent, ref } from 'vue';const inputValue = ref('');const loading = ref(false);const onInputChange = (e) => { console.log('input change---', e);};const onSubmit = (e) => { loading.value = true; console.log('input submit---', e);};const onCancel = () => { loading.value = false; console.log('input cancel');};</script>5. MarkDown 卡片
用于显示 MarkDown 内容的卡片组件
5.1. 引入
import { McMarkdownCard } from '@matechat/core';5.2. 参数
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| content | string | '' | MarkDown文本 |
| theme | Theme + 'light' + 'dark' | 'light' | MarkDown卡片主题 |
| mdOptions | object | {} | 设置 markdown 对字符串的处理方式， 可参考markdown-it |
| mdPlugins | MdPlugin[] | [] | 设置 markdown-it 插件 |
| customXssRules | CustomXssRule[] | [] | 自定义 xss 对某种 tag 的过滤方式，每条规则需要指定 tag, 并给出需要加入白名单的属性数组 |
| enableThink | boolean | false | 是否开启标签识别 |
| thinkOptions | ThinkOptions | -- | 标签配置，自定义样式等 |
| typing | boolean | false | 开启打字机效果 |
| typingOptions | TypingOptions | { step: 2, interval: 50, style: 'normal' } | 打字机效果配置 |
5.3. Demo
<template> <McMarkdownCard :content="content" :theme="theme"></McMarkdownCard></template><script setup>import { ref, onMounted } from 'vue';let themeService;const theme = ref('light');const content = ref(`# 快速排序（Quick Sort）### 介绍`)三、按需引入与 Tree-Shaking
MateChat 本身提供 完整注册 与 按需引入 两种方式：
// 方式一：一次性全局引入import MateChat from '@matechat/core';app.use(MateChat);// 方式二：仅引入所需import { McBubble, McInput } from '@matechat/core';app.component('McBubble', McBubble);app.component('McInput', McInput);推荐在生产环境使用方式二，配合 Vite + ESBuild 的 Tree-Shaking，可显著减小最终 bundle。
四、主题定制三步曲
MateChat 内置 DevUI 6.x 的主题系统，所有颜色、圆角、阴影都映射到 CSS 变量，默认提供 亮色 / 暗色 两套。你可以：
1. 选择内置暗色
import 'vue-devui/style/theme/dark.css'2. 覆盖单个变量（推荐）
:root { --devui-brand: #ff5722; // 主品牌色 --devui-primary-bg: #fff7f5; // 气泡背景 --mc-bubble-radius: 12px; // 自定义气泡圆角}3. 完全自定义主题文件
- 复制官方 light.css 为 my-brand.css修改变量后全局引入可按需切换：document.documentElement.setAttribute('data-theme','my-brand')
只要保持变量名不变，MateChat 的所有组件都会即时响应，无需额外配置。
五、实战建议
| 需求 | 官方推荐 |
|---|---|
| 长对话滚动性能 | 给 McLayoutContent 加 virtual-scroll（由业务实现），或在 500+ 条时裁剪历史 |
| 代码高亮洞察 | 在 McMarkDown 内部注入 highlight.js 自动扫描 |
| 多会话 | 用 Pinia/Zustand 保存多组 messages，每组挂一个 McLayout |
| “发送中” 动画 | 先 push loading:true 的空气泡，流式响应到达后再填充 content |
六、总结
- MateChat 组件层面 已经覆盖了 AI 聊天基本的 “布局-消息-输入-快捷操作-欢迎页” 闭环；主题系统 继承 DevUI，改变量即可一键换肤；官方还在演进 McMarkdown 富文档卡片、文件/图片上传 等组件。
