finyx_frontend/docs/COMPONENTS.md

组件使用文档

概述

本文档说明项目中全局组件的使用方法和API。

组件注册

所有全局组件在 src/components/index.ts 中注册，在 src/main.ts 中通过 app.use(Components) 全局注册。

布局组件

LayoutContainer

布局容器组件，用于包裹页面内容。

<template>
  <LayoutContainer>
    <!-- 页面内容 -->
  </LayoutContainer>
</template>

LoginContainer

登录容器组件，用于登录页面布局。

<template>
  <LoginContainer>
    <!-- 登录表单 -->
  </LoginContainer>
</template>

业务组件

CardBox

通用卡片组件，用于展示卡片式内容。

<template>
  <CardBox
    :title="'标题'"
    :description="'描述'"
    :image="imageUrl"
    @click="handleClick"
  />
</template>

Props:

• title: 卡片标题
• description: 卡片描述
• image: 卡片图片URL
• 其他自定义props

Events:

• click: 点击事件

CardBoxAgent

智能体卡片组件，用于展示智能体信息。

<template>
  <CardBoxAgent
    :agent="agentData"
    @click="handleClick"
    @edit="handleEdit"
    @delete="handleDelete"
  />
</template>

Props:

• agent: 智能体数据对象

Events:

• click: 点击事件
• edit: 编辑事件
• delete: 删除事件

CardBoxDataset

数据集卡片组件，用于展示知识库信息。

<template>
  <CardBoxDataset
    :dataset="datasetData"
    @click="handleClick"
  />
</template>

Props:

• dataset: 数据集数据对象

Events:

• click: 点击事件

CardAdd

添加卡片组件，用于添加新项。

<template>
  <CardAdd @click="handleAdd" />
</template>

Events:

• click: 点击添加事件

CardCheckbox

带复选框的卡片组件。

<template>
  <CardCheckbox
    v-model="checked"
    :data="cardData"
  />
</template>

Props:

• modelValue: 是否选中
• data: 卡片数据

Events:

• update:modelValue: 选中状态更新

表格组件

AppTable

增强的表格组件，基于Element Plus Table封装。

<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。

<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预览组件。

<template>
  <MdPreview
    :modelValue="content"
    editorId="preview-1"
  />
</template>

Props:

• modelValue: Markdown内容
• editorId: 编辑器唯一ID
• 其他md-editor-v3的props

MdEditorMagnify

Markdown编辑器放大模式。

<template>
  <MdEditorMagnify
    v-model="content"
  />
</template>

NewMdPreview

新版Markdown预览组件。

<template>
  <NewMdPreview
    :content="markdownContent"
  />
</template>

其他组件

AppAvatar

头像组件。

<template>
  <AppAvatar
    :src="avatarUrl"
    :size="40"
    :name="userName"
  />
</template>

Props:

• src: 头像图片URL
• size: 头像大小
• name: 用户名（用于生成默认头像）

AppIcon

应用图标组件。

<template>
  <AppIcon name="icon-name" />
</template>

Props:

• name: 图标名称

BackButton

返回按钮组件。

<template>
  <BackButton @click="handleBack" />
</template>

Events:

• click: 点击事件

InfiniteScroll

无限滚动组件。

<template>
  <InfiniteScroll
    :loading="loading"
    :finished="finished"
    @load="handleLoad"
  >
    <!-- 列表内容 -->
  </InfiniteScroll>
</template>

Props:

• loading: 加载中状态
• finished: 是否加载完成

Events:

• load: 加载更多事件

AutoTooltip

自动提示组件，文本溢出时显示tooltip。

<template>
  <AutoTooltip :content="longText" />
</template>

Props:

• content: 文本内容
• maxWidth: 最大宽度

TagEllipsis

标签省略组件，多个标签时自动省略。

<template>
  <TagEllipsis
    :tags="tagList"
    :max="3"
  />
</template>

Props:

• tags: 标签数组
• max: 最大显示数量

TagInputWrapper

标签输入包装组件。

<template>
  <TagInputWrapper
    v-model="tags"
    :placeholder="'请输入标签'"
  />
</template>

Props:

• modelValue: 标签数组
• placeholder: 占位符

Events:

• update:modelValue: 标签更新事件

TopTabs

顶部标签页组件。

<template>
  <TopTabs
    v-model="activeTab"
    :tabs="tabList"
  />
</template>

Props:

• modelValue: 当前激活的标签
• tabs: 标签列表

Events:

• update:modelValue: 标签切换事件

DialogBox

对话框组件。

<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

"仅我的"筛选组件。

<template>
  <JustMine
    v-model="justMine"
    @change="handleChange"
  />
</template>

Props:

• modelValue: 是否仅显示我的

Events:

• update:modelValue: 状态更新
• change: 变化事件

AppLink

应用链接组件。

<template>
  <AppLink
    :to="{ name: 'routeName' }"
    :target="'_blank'"
  >
    链接文本
  </AppLink>
</template>

Props:

• to: 路由目标
• target: 打开方式

CommonList

通用列表组件。

<template>
  <CommonList
    :data="listData"
    :loading="loading"
    @item-click="handleItemClick"
  />
</template>

Props:

• data: 列表数据
• loading: 加载状态

Events:

• item-click: 列表项点击事件

ReadWrite

读写组件，用于展示可编辑内容。

<template>
  <ReadWrite
    v-model="content"
    :readonly="readonly"
  />
</template>

Props:

• modelValue: 内容
• readonly: 是否只读

Events:

• update:modelValue: 内容更新

Logo组件

LogoFull

完整Logo组件。

<template>
  <LogoFull />
</template>

LogoIcon

Logo图标组件。

<template>
  <LogoIcon />
</template>

SendIcon

发送图标组件。

<template>
  <SendIcon />
</template>

动态表单组件

DynamicsForm

动态表单组件，支持根据配置动态生成表单。

<template>
  <DynamicsForm
    :config="formConfig"
    v-model="formData"
    @submit="handleSubmit"
  />
</template>

Props:

• config: 表单配置
• modelValue: 表单数据

Events:

• update:modelValue: 表单数据更新
• submit: 提交事件

图表组件

AppCharts

图表组件，基于ECharts封装。

<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. 组件会自动全局注册

示例：

// 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)
  }
}