x-sccba — Vue 3 使用指南

基于 Element Plus 的增强组件库，提供丰富的业务组件与 AI 交互组件，完整支持 Vue 3 + Composition API。

目录

• 环境要求
• 安装依赖
• 快速上手
• 按需引入
• 组件列表
• Hooks
• ConfigProvider
• 常见问题

环境要求

| 依赖 | 版本要求 | |------|---------| | Node.js | >= 16 | | Vue | ^3.0.0 | | Element Plus | >= 2.0.0 |

安装依赖

# 安装 Element Plus（必须，peerDependency 由使用者提供）
npm install element-plus

# 安装 Element Plus 图标（必须，peerDependency 由使用者提供）
npm install @element-plus/icons-vue

# 安装 x-sccba
npm install x-sccba

快速上手

main.ts

import { createApp } from 'vue'
import App from './App.vue'

// 1. 引入 Element Plus
import ElementPlus from 'element-plus'
import * as ElementPlusNS from 'element-plus'
import 'element-plus/dist/index.css'

// 2. 引入 x-sccba
import ElementPlusX from 'x-sccba'

const app = createApp(App)

// 3. 先注册 Element Plus
app.use(ElementPlus)

// 4. 再注册 x-sccba，并通过 { ui } 传入命名空间对象
//    注意：必须使用 import * as 的命名空间导入，不能传 default 导出
app.use(ElementPlusX, { ui: ElementPlusNS })

app.mount('#app')

为什么要传 ElementPlusNS？ x-sccba 内部通过 ui 对象按组件名动态查找 ElButton、ElInput 等， 必须传入含所有 El* 导出的命名空间对象（import * as）， 而非仅有 install/version 的 default 导出。

在组件中使用

<template>
  <XButton type="primary">点击</XButton>
  <XInput v-model="value" placeholder="请输入" />
  <XSender v-model="text" @submit="handleSubmit" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const text = ref('')

function handleSubmit(val: string) {
  console.log('发送:', val)
}
</script>

按需引入

不使用全局注册，可直接按需导入组件：

import { XButton, XInput, XSender, XBubble } from 'x-sccba'

使用前仍需在入口文件完成 app.use(ElementPlusX, { ui: ElementPlusNS }) 注册， 以确保内部 UI 组件查找链正常工作。

组件列表

基础组件（Element Plus 增强封装）

| 组件名 | 说明 | |--------|------| | XButton | 按钮 | | XInput | 输入框 | | XInputNumber | 数字输入框 | | XInputTag | 标签输入框 | | XSelect | 选择器 | | XCascader / XCascaderPanel | 级联选择器 | | XCheckbox / XCheckboxGroup / XCheckboxButton | 复选框 | | XRadio / XRadioGroup / XRadioButton | 单选框 | | XSwitch | 开关 | | XSlider | 滑块 | | XRate | 评分 | | XColorPicker | 颜色选择器 | | XDatePicker | 日期选择器 | | XTimePicker | 时间选择器 | | XTimeSelect | 时间选择 | | XUpload | 文件上传 | | XMention | 提及 | | XAutocomplete | 自动补全 |

数据展示

| 组件名 | 说明 | |--------|------| | XTable | 表格 | | XVirtualTable | 虚拟滚动表格 | | XVirtualizedSelect | 虚拟化选择器 | | XTree | 树形控件 | | XTreeSelect | 树形选择 | | XTreeV2 | 虚拟化树 | | XPagination | 分页 | | XTag | 标签 | | XBadge | 徽章 | | XAvatar / XAvatarGroup | 头像 | | XImage / XImageViewer | 图片 | | XProgress | 进度条 | | XCalendar | 日历 | | XStatistic / XCountdown | 统计数值 / 倒计时 | | XTimeline / XTimelineItem | 时间线 | | XDescriptions / XDescriptionsItem | 描述列表 | | XCard | 卡片 | | XCarousel / XCarouselItem | 走马灯 | | XCollapse / XCollapseItem | 折叠面板 | | XTabs / XTabPane | 标签页 | | XSteps / XStep | 步骤条 | | XSkeleton / XSkeletonItem | 骨架屏 | | XEmpty | 空状态 | | XResult | 结果 | | XText | 文本 |

导航

| 组件名 | 说明 | |--------|------| | XMenu / XMenuItem / XSubMenu / XMenuItemGroup | 菜单 | | XBreadcrumb / XBreadcrumbItem | 面包屑 | | XTabs | 标签页 | | XAnchor / XAnchorLink | 锚点 | | XPageHeader | 页头 | | XAffix | 固钉 | | XBacktop | 回到顶部 |

反馈

| 组件名 | 说明 | |--------|------| | XDialog | 对话框 | | XDrawer | 抽屉 | | XTooltip | 文字提示 | | XPopover | 弹出框 | | XPopconfirm | 气泡确认框 | | XAlert | 警告 | | XTour / XTourStep | 漫游式引导 |

布局

| 组件名 | 说明 | |--------|------| | XRow / XCol | 栅格 | | XContainer / XHeader / XAside / XMain / XFooter | 容器 | | XSpace | 间距 | | XDivider | 分割线 | | XScrollbar | 滚动条 | | XWatermark | 水印 |

其他

| 组件名 | 说明 | |--------|------| | XTransfer | 穿梭框 | | XSegmented | 分段控制器 | | XDropdown / XDropdownItem / XDropdownMenu | 下拉菜单 | | XLink | 文字链接 | | XIcon | 图标 | | XForm / XFormItem | 表单 |

AI 交互组件（x-sccba 特色）

| 组件名 | 说明 | |--------|------| | XSender | AI 对话输入框，支持语音、粘贴文件、Shift+Enter、触发字符弹窗 | | XMentionSender | 带 @ 提及功能的对话输入框 | | XEditorSender | 富文本编辑器输入框 | | XBubble | 对话气泡，支持打字机效果、Markdown 渲染、头像 | | XBubbleList | 对话气泡列表 | | XTypewriter | 打字机动画组件 | | XThinking | AI 思考状态展示（展开/收起动画） | | XThoughtChain | 思维链展示 | | XMarkdown | Markdown 渲染（支持代码高亮、数学公式、流程图） | | XMarkdownAsync | 异步流式 Markdown 渲染 | | XConversations | 会话列表 | | XAttachments | 附件展示 | | XFilesCard | 文件卡片 | | XPrompts | 提示词列表 |

业务组件

| 组件名 | 说明 | |--------|------| | XQueryCondition | 查询条件栏（支持展开/收起、多行布局） | | ConfigProvider | 全局配置（Markdown 插件等） |

Hooks

所有 Hook 均可从 x-sccba 直接导入：

import {
  useMessage,
  useMessageBox,
  useNotification,
  useLoading,
  useLocale,
  useForwardProps,
  useOmitForwardProps
} from 'x-sccba'

useMessage

封装 ElMessage，统一默认配置：

const { message } = useMessage({ duration: 3000, showClose: true })

message.success('操作成功')
message.error('操作失败')
message.warning('警告')
message.info('提示')
message.closeAll()

useMessageBox

封装 ElMessageBox：

const { alert, confirm, prompt, close } = useMessageBox({
  confirmButtonText: '确定',
  cancelButtonText: '取消'
})

confirm('确定删除吗？').then(() => {
  // 用户点击确定
}).catch(() => {
  // 用户取消
})

const { value } = await prompt('请输入名称', '新建')

useNotification

封装 ElNotification：

const { notification } = useNotification({
  duration: 4500,
  position: 'top-right'
})

notification.success('操作成功')
notification.error({ title: '错误', message: '详细信息' })
notification.closeAll()

useLoading

封装 ElLoading：

const { open, closeAll } = useLoading({
  text: '加载中...',
  background: 'rgba(0,0,0,0.7)'
})

const instance = open()
// 完成后关闭
instance.close()

// 或关闭全部
closeAll()

useLocale

获取当前国际化上下文（与 Element Plus locale 系统联动）：

const { t, lang } = useLocale()
console.log(lang.value) // 'zh-cn'
console.log(t('button.submit'))

useForwardProps / useOmitForwardProps

在封装组件时，精确转发父组件实际传入的 props，避免 Vue3 布尔值类型强制转换问题：

// 只转发父级实际传入的 props
const forwarded = useForwardProps(props)

// 转发时排除某些 props
const forwarded = useOmitForwardProps(props, ['modelValue', 'onUpdate:modelValue'])

ConfigProvider

用于配置全局 Markdown 解析选项（自定义 markdown-it 实例或插件）：

<template>
  <ConfigProvider :md="customMd" :md-plugins="extraPlugins">
    <App />
  </ConfigProvider>
</template>

<script setup lang="ts">
import MarkdownIt from 'markdown-it'

const customMd = new MarkdownIt({ html: true, linkify: true })
const extraPlugins = [/* markdown-it 插件 */]
</script>

常见问题

Q: 报错 [x-sccba] UI framework not provided

确认 app.use(ElementPlusX, { ui: ElementPlusNS }) 中 ui 使用的是 import * as ElementPlusNS from 'element-plus' 的命名空间导入，而不是 import ElementPlusNS from 'element-plus'。

Q: 组件样式缺失

确认已在入口引入 Element Plus 样式：

import 'element-plus/dist/index.css'

Q: TypeScript 类型提示缺失

确认 tsconfig.json 中包含 node_modules/x-sccba/types/index.d.ts，或添加：

{
  "compilerOptions": {
    "types": ["x-sccba"]
  }
}