572 lines
8.6 KiB
Markdown
572 lines
8.6 KiB
Markdown
# 组件使用文档
|
||
|
||
## 概述
|
||
|
||
本文档说明项目中全局组件的使用方法和API。
|
||
|
||
## 组件注册
|
||
|
||
所有全局组件在 `src/components/index.ts` 中注册，在 `src/main.ts` 中通过 `app.use(Components)` 全局注册。
|
||
|
||
## 布局组件
|
||
|
||
### LayoutContainer
|
||
布局容器组件，用于包裹页面内容。
|
||
|
||
```vue
|
||
<template>
|
||
<LayoutContainer>
|
||
<!-- 页面内容 -->
|
||
</LayoutContainer>
|
||
</template>
|
||
```
|
||
|
||
### LoginContainer
|
||
登录容器组件，用于登录页面布局。
|
||
|
||
```vue
|
||
<template>
|
||
<LoginContainer>
|
||
<!-- 登录表单 -->
|
||
</LoginContainer>
|
||
</template>
|
||
```
|
||
|
||
## 业务组件
|
||
|
||
### CardBox
|
||
通用卡片组件，用于展示卡片式内容。
|
||
|
||
```vue
|
||
<template>
|
||
<CardBox
|
||
:title="'标题'"
|
||
:description="'描述'"
|
||
:image="imageUrl"
|
||
@click="handleClick"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `title`: 卡片标题
|
||
- `description`: 卡片描述
|
||
- `image`: 卡片图片URL
|
||
- 其他自定义props
|
||
|
||
**Events:**
|
||
- `click`: 点击事件
|
||
|
||
### CardBoxAgent
|
||
智能体卡片组件，用于展示智能体信息。
|
||
|
||
```vue
|
||
<template>
|
||
<CardBoxAgent
|
||
:agent="agentData"
|
||
@click="handleClick"
|
||
@edit="handleEdit"
|
||
@delete="handleDelete"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `agent`: 智能体数据对象
|
||
|
||
**Events:**
|
||
- `click`: 点击事件
|
||
- `edit`: 编辑事件
|
||
- `delete`: 删除事件
|
||
|
||
### CardBoxDataset
|
||
数据集卡片组件，用于展示知识库信息。
|
||
|
||
```vue
|
||
<template>
|
||
<CardBoxDataset
|
||
:dataset="datasetData"
|
||
@click="handleClick"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `dataset`: 数据集数据对象
|
||
|
||
**Events:**
|
||
- `click`: 点击事件
|
||
|
||
### CardAdd
|
||
添加卡片组件，用于添加新项。
|
||
|
||
```vue
|
||
<template>
|
||
<CardAdd @click="handleAdd" />
|
||
</template>
|
||
```
|
||
|
||
**Events:**
|
||
- `click`: 点击添加事件
|
||
|
||
### CardCheckbox
|
||
带复选框的卡片组件。
|
||
|
||
```vue
|
||
<template>
|
||
<CardCheckbox
|
||
v-model="checked"
|
||
:data="cardData"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 是否选中
|
||
- `data`: 卡片数据
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 选中状态更新
|
||
|
||
## 表格组件
|
||
|
||
### AppTable
|
||
增强的表格组件，基于Element Plus Table封装。
|
||
|
||
```vue
|
||
<template>
|
||
<AppTable
|
||
:data="tableData"
|
||
:columns="columns"
|
||
:loading="loading"
|
||
@selection-change="handleSelectionChange"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `data`: 表格数据
|
||
- `columns`: 列配置
|
||
- `loading`: 加载状态
|
||
- 其他Element Plus Table的props
|
||
|
||
**Events:**
|
||
- `selection-change`: 选择变化事件
|
||
- 其他Element Plus Table的事件
|
||
|
||
## 编辑器组件
|
||
|
||
### MdEditor
|
||
Markdown编辑器组件，基于md-editor-v3。
|
||
|
||
```vue
|
||
<template>
|
||
<MdEditor
|
||
v-model="content"
|
||
:height="400"
|
||
:toolbars="toolbars"
|
||
/>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
import { ref } from 'vue'
|
||
|
||
const content = ref('# Hello World')
|
||
const toolbars = ['bold', 'italic', 'underline']
|
||
</script>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 编辑器内容
|
||
- `height`: 编辑器高度
|
||
- `toolbars`: 工具栏配置
|
||
- 其他md-editor-v3的props
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 内容更新事件
|
||
- 其他md-editor-v3的事件
|
||
|
||
### MdPreview
|
||
Markdown预览组件。
|
||
|
||
```vue
|
||
<template>
|
||
<MdPreview
|
||
:modelValue="content"
|
||
editorId="preview-1"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: Markdown内容
|
||
- `editorId`: 编辑器唯一ID
|
||
- 其他md-editor-v3的props
|
||
|
||
### MdEditorMagnify
|
||
Markdown编辑器放大模式。
|
||
|
||
```vue
|
||
<template>
|
||
<MdEditorMagnify
|
||
v-model="content"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
### NewMdPreview
|
||
新版Markdown预览组件。
|
||
|
||
```vue
|
||
<template>
|
||
<NewMdPreview
|
||
:content="markdownContent"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
## 其他组件
|
||
|
||
### AppAvatar
|
||
头像组件。
|
||
|
||
```vue
|
||
<template>
|
||
<AppAvatar
|
||
:src="avatarUrl"
|
||
:size="40"
|
||
:name="userName"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `src`: 头像图片URL
|
||
- `size`: 头像大小
|
||
- `name`: 用户名（用于生成默认头像）
|
||
|
||
### AppIcon
|
||
应用图标组件。
|
||
|
||
```vue
|
||
<template>
|
||
<AppIcon name="icon-name" />
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `name`: 图标名称
|
||
|
||
### BackButton
|
||
返回按钮组件。
|
||
|
||
```vue
|
||
<template>
|
||
<BackButton @click="handleBack" />
|
||
</template>
|
||
```
|
||
|
||
**Events:**
|
||
- `click`: 点击事件
|
||
|
||
### InfiniteScroll
|
||
无限滚动组件。
|
||
|
||
```vue
|
||
<template>
|
||
<InfiniteScroll
|
||
:loading="loading"
|
||
:finished="finished"
|
||
@load="handleLoad"
|
||
>
|
||
<!-- 列表内容 -->
|
||
</InfiniteScroll>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `loading`: 加载中状态
|
||
- `finished`: 是否加载完成
|
||
|
||
**Events:**
|
||
- `load`: 加载更多事件
|
||
|
||
### AutoTooltip
|
||
自动提示组件，文本溢出时显示tooltip。
|
||
|
||
```vue
|
||
<template>
|
||
<AutoTooltip :content="longText" />
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `content`: 文本内容
|
||
- `maxWidth`: 最大宽度
|
||
|
||
### TagEllipsis
|
||
标签省略组件，多个标签时自动省略。
|
||
|
||
```vue
|
||
<template>
|
||
<TagEllipsis
|
||
:tags="tagList"
|
||
:max="3"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `tags`: 标签数组
|
||
- `max`: 最大显示数量
|
||
|
||
### TagInputWrapper
|
||
标签输入包装组件。
|
||
|
||
```vue
|
||
<template>
|
||
<TagInputWrapper
|
||
v-model="tags"
|
||
:placeholder="'请输入标签'"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 标签数组
|
||
- `placeholder`: 占位符
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 标签更新事件
|
||
|
||
### TopTabs
|
||
顶部标签页组件。
|
||
|
||
```vue
|
||
<template>
|
||
<TopTabs
|
||
v-model="activeTab"
|
||
:tabs="tabList"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 当前激活的标签
|
||
- `tabs`: 标签列表
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 标签切换事件
|
||
|
||
### DialogBox
|
||
对话框组件。
|
||
|
||
```vue
|
||
<template>
|
||
<DialogBox
|
||
v-model="visible"
|
||
:title="'标题'"
|
||
:width="'600px'"
|
||
>
|
||
<!-- 对话框内容 -->
|
||
</DialogBox>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 是否显示
|
||
- `title`: 标题
|
||
- `width`: 宽度
|
||
- 其他Element Plus Dialog的props
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 显示状态更新
|
||
- 其他Element Plus Dialog的事件
|
||
|
||
### JustMine
|
||
"仅我的"筛选组件。
|
||
|
||
```vue
|
||
<template>
|
||
<JustMine
|
||
v-model="justMine"
|
||
@change="handleChange"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 是否仅显示我的
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 状态更新
|
||
- `change`: 变化事件
|
||
|
||
### AppLink
|
||
应用链接组件。
|
||
|
||
```vue
|
||
<template>
|
||
<AppLink
|
||
:to="{ name: 'routeName' }"
|
||
:target="'_blank'"
|
||
>
|
||
链接文本
|
||
</AppLink>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `to`: 路由目标
|
||
- `target`: 打开方式
|
||
|
||
### CommonList
|
||
通用列表组件。
|
||
|
||
```vue
|
||
<template>
|
||
<CommonList
|
||
:data="listData"
|
||
:loading="loading"
|
||
@item-click="handleItemClick"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `data`: 列表数据
|
||
- `loading`: 加载状态
|
||
|
||
**Events:**
|
||
- `item-click`: 列表项点击事件
|
||
|
||
### ReadWrite
|
||
读写组件，用于展示可编辑内容。
|
||
|
||
```vue
|
||
<template>
|
||
<ReadWrite
|
||
v-model="content"
|
||
:readonly="readonly"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `modelValue`: 内容
|
||
- `readonly`: 是否只读
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 内容更新
|
||
|
||
### Logo组件
|
||
|
||
#### LogoFull
|
||
完整Logo组件。
|
||
|
||
```vue
|
||
<template>
|
||
<LogoFull />
|
||
</template>
|
||
```
|
||
|
||
#### LogoIcon
|
||
Logo图标组件。
|
||
|
||
```vue
|
||
<template>
|
||
<LogoIcon />
|
||
</template>
|
||
```
|
||
|
||
#### SendIcon
|
||
发送图标组件。
|
||
|
||
```vue
|
||
<template>
|
||
<SendIcon />
|
||
</template>
|
||
```
|
||
|
||
## 动态表单组件
|
||
|
||
### DynamicsForm
|
||
动态表单组件，支持根据配置动态生成表单。
|
||
|
||
```vue
|
||
<template>
|
||
<DynamicsForm
|
||
:config="formConfig"
|
||
v-model="formData"
|
||
@submit="handleSubmit"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `config`: 表单配置
|
||
- `modelValue`: 表单数据
|
||
|
||
**Events:**
|
||
- `update:modelValue`: 表单数据更新
|
||
- `submit`: 提交事件
|
||
|
||
## 图表组件
|
||
|
||
### AppCharts
|
||
图表组件，基于ECharts封装。
|
||
|
||
```vue
|
||
<template>
|
||
<AppCharts
|
||
:option="chartOption"
|
||
:height="400"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
**Props:**
|
||
- `option`: ECharts配置项
|
||
- `height`: 图表高度
|
||
|
||
## 使用注意事项
|
||
|
||
1. **组件导入**: 全局组件无需导入，直接使用组件名即可
|
||
2. **Props验证**: 所有组件都使用TypeScript类型定义，IDE会有类型提示
|
||
3. **事件命名**: 事件使用kebab-case命名（如 `@update-value`）
|
||
4. **样式作用域**: 组件样式使用scoped，不会影响外部样式
|
||
5. **响应式**: 所有组件都支持Vue 3的响应式系统
|
||
|
||
## 自定义组件开发
|
||
|
||
如果需要开发新的全局组件：
|
||
|
||
1. 在 `src/components/` 下创建组件目录
|
||
2. 创建 `index.vue` 文件
|
||
3. 在 `src/components/index.ts` 中注册组件
|
||
4. 组件会自动全局注册
|
||
|
||
示例：
|
||
```typescript
|
||
// src/components/my-component/index.vue
|
||
<template>
|
||
<div class="my-component">
|
||
<!-- 组件内容 -->
|
||
</div>
|
||
</template>
|
||
|
||
<script setup lang="ts">
|
||
// 组件逻辑
|
||
</script>
|
||
|
||
// src/components/index.ts
|
||
import MyComponent from './my-component/index.vue'
|
||
|
||
export default {
|
||
install(app: App) {
|
||
app.component('MyComponent', MyComponent)
|
||
}
|
||
}
|
||
```
|
||
|