通用组件

项目的通用组件位于 src/components/core，覆盖后台系统中高频出现的搜索、表单、表格、图表、布局和媒体能力。组件库的目标是统一交互与视觉基线，不是把所有业务页面都抽象成配置文件。

组件分类

当前主要目录：

分类	目录	典型能力
基础	base	Logo、安全 HTML、SVG 图标、返回顶部
表单	forms	搜索、动态表单、上传、资源选择、富文本
表格	tables	表格、表头、列搜索、图片、导出弹窗
图表	charts	折线、柱状、雷达、漏斗、热力、K 线等
卡片	cards	统计、趋势、进度、时间线和图表卡片
布局	layouts	页面容器、顶部栏、菜单、标签、设置面板
媒体	media	图片裁剪、视频播放
文本效果	text-effect	数字动画和滚动文本
结果与异常	views	登录、异常页和结果页基础视图
小部件	widget	图标按钮、数据大屏控件

自动注册

Vite 通过 unplugin-vue-components 自动扫描 src/components，并按需解析 Element Plus 组件。因此页面模板通常可以直接使用：

<template>
  <ArtPageContent>
    <ArtSearchBar v-model="searchForm" :items="searchItems" @search="handleSearch" />
    <ArtTable :data="data" :loading="loading" />
  </ArtPageContent>
</template>

开发环境会生成 src/types/import/components.d.ts，为模板中的全局组件提供 TypeScript 类型。新增组件后如果编辑器暂未识别，可以重启开发服务重新生成声明。

高频组件

ArtSearchBar

用于统一列表页筛选区域，适合文本、选择器、日期范围等常规搜索条件。页面负责搜索字段和提交逻辑，组件负责布局、展开收起和操作区一致性。

ArtForm

用于结构化表单配置和通用表单布局。复杂业务表单仍可以直接使用 Element Plus 表单组件，但应保留项目的间距、校验和按钮规范。

ArtTable 与 ArtTableHeader

ArtTable 提供统一表格外观和常用能力，ArtTableHeader 组织标题、刷新、列设置和页面操作。通常与 useTable、useTableColumns 配合使用。

ArtSafeHtml

用于需要展示受控富文本的场景。不要直接使用 v-html 渲染用户输入；即使使用安全组件，服务端也应执行内容校验和存储策略。

ArtFileUpload 与 ArtAssetPicker

上传和资源选择组件统一文件交互，但真实上传地址、鉴权和文件访问策略仍需要接入客户后端。纯前端预置数据不能替代对象存储或文件服务。

图表组件

项目提供多类 ECharts 组件。通用图表组件负责容器、主题和基础配置，页面负责指标口径、数据转换和空状态。复杂图表优先通过 props 和 formatter 扩展，不在通用组件中写死某个业务模块。

页面局部组件

只服务于单个页面的组件应放在页面模块内：

src/views/customer/list/
├── index.vue
└── modules/
    ├── CustomerDialog.vue
    ├── CustomerDetail.vue
    └── customerColumns.ts

当组件满足以下条件后，再考虑提升到 src/components/core：

• 已在至少两个独立业务域复用。
• props、事件和插槽可以脱离原页面理解。
• 视觉和交互具有全局一致性价值。
• 不依赖特定 API、Store 或路由名称。

组件接口设计

推荐保持单向数据流：

<CustomerDialog
  v-model="dialogVisible"
  :customer="editingCustomer"
  @success="handleRefresh"
/>

• props 传入状态和配置。
• emits 通知业务事件。
• v-model 只用于明确的双向状态。
• 插槽用于开放布局位置，不用于绕过组件职责。
• 组件内部不直接修改父级对象。

公共组件应为 props、emits 和暴露方法提供 TypeScript 类型。

Element Plus 的使用

项目以 Element Plus 作为基础组件库，并通过 Sass 源码接入主题。业务页面可以直接使用 Element Plus，但应遵循：

• 先检查项目是否已有更高层的 Art 组件。
• 相同功能保持一致的尺寸、状态和反馈方式。
• MessageBox 按钮使用项目国际化默认值。
• 不在页面中大面积覆盖组件库内部选择器。
• 全局视觉调整放在主题或设计令牌层。

状态与边界

通用组件应该明确处理以下状态：

• loading
• empty
• disabled
• error
• readonly
• 超长文本和小屏布局

组件不应该悄悄伪造成功。上传、保存和删除等操作如果尚未接入后端，应由业务页面显示真实边界。

新增公共组件流程

1. 先在业务页面验证交互和 API 是否稳定。
2. 移除业务域名称和接口依赖。
3. 定义 props、emits、slots 和默认状态。
4. 覆盖 loading、空数据、禁用和异常场景。
5. 在不同主题和常用视口下验证。
6. 确认自动注册类型声明正常生成。
7. 在真实页面中至少完成一次复用验证。

常见问题

自动注册后是否完全不需要 import

模板中的组件通常不需要。若在 TypeScript 中引用组件类型、动态组件对象或测试文件中直接使用，仍需要显式 import。

所有表单都应该使用 ArtForm 吗

不需要。标准化程度高的表单适合配置式组件，复杂联动或高度定制的流程可以直接组合 Element Plus，但应保持项目设计规范。

为什么不把页面全部配置化

过度配置化会隐藏业务流程、降低类型推导质量，并让复杂交互难以维护。组件抽象应减少真实重复，而不是追求“页面没有模板代码”。

表格组合方案见表格与列表体系，组合式逻辑见Hooks 与组合式能力。