@zy-frontend/business

基于 Vue 3 + TypeScript + Element Plus 的中后台业务组件库，提供检索、列表、图表、布局、评分等开箱即用的配置化组件，以及配套的 Hooks / Utils / Service 层。

特性

• 配置化驱动：通过 JSON 风格的 props 描述表单/列表/图表/布局，少量代码完成复杂业务页面
• TypeScript 全量类型：所有组件、Props、Hooks 均带类型定义
• 全局上下文注入：统一管理 request、projectId、eventId、getDataStructure 等，组件内部自动消费

安装

npm i @zy-frontend/business
# 或
pnpm add @zy-frontend/business

Peer 依赖

本库将以下依赖视为 peer，需由消费方提供：

| 依赖 | 说明 | | -------------------------------- | ----- | | vue | ^3.5 | | element-plus | ^2.13 | | axios | ^1.7 | | @zy-frontend/element-plus-form | ^2.0 |

echarts / exceljs / lodash-es / dayjs 已 external，使用对应组件（如 ZYChartList、ColumnCustomizableTable 的导出功能）时需在消费方项目中安装。

快速开始

1. 注册组件库（可选）

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

import { ZYGlobalProvider } from '@zy-frontend/business'
import '@zy-frontend/business/dist/style.css'

import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.use(ZYGlobalProvider) // 仅注册全局组件，不自动注入配置
app.mount('#app')

注意：app.use(ZYGlobalProvider) 只是把组件注册到全局，并不会真正注入全局配置。你必须用 <ZYGlobalProvider> 包裹业务根节点（见下一步）才能完成注入。

2. 在根组件提供全局配置

<!-- App.vue -->
<script setup lang="ts">
import axios from 'axios'
import { ZYGlobalProvider } from '@zy-frontend/business'

const request = axios.create({ baseURL: '/api' })

// 静态值
const projectId = 100
const eventId = 1

// 或动态获取（任选其一）
// const getProjectId = () => store.state.projectId
</script>

<template>
  <ZYGlobalProvider
    :request="request"
    :project-id="projectId"
    :event-id="eventId"
    :get-data-structure="getDataStructure"
  >
    <RouterView />
  </ZYGlobalProvider>
</template>

3. 使用组件

<script setup lang="ts">
import { ZYTable, ZYSearchForm, ZYAdvancedSearch } from '@zy-frontend/business'
</script>

<template>
  <ZYSearchForm :config="formConfig" @search="onSearch" />
  <ZYTable :config="tableConfig" :request-fn="fetchList" />
</template>

组件

| 组件 | 说明 | | ---------------------------------- | --------------------------------------------------------------------- | | ZYGlobalProvider | 全局配置提供者，注入 request / projectId / eventId / getDataStructure | | ZYTable / ZYSimpleTable | 配置化列表，支持分页、排序、操作列、自定义渲染 | | ZYSearchForm | 配置化检索表单，支持展开/收起、字段选择器 | | ZYAdvancedSearch | 高级检索，支持复杂条件树、字段选择、历史记录 | | ZYColumnCustomizableTable | 自定义列表表格，支持列配置、导出模板 | | ZYChartList / ZYChart | 配置化图表，基于 ECharts | | ZYLayout / ZYLayoutItem | 配置化网格布局 | | ZYAnchorTabs / ZYAnchorTabItem | 锚点定位垂直标签页 | | ZYSplitter / ZYSplitterPanel | 拖拽分屏面板 | | ZYSortableFieldPicker | 字段选择器，支持拖拽排序 | | ZYScoreTable / ZYScoreDialog | 评分组件（GCS / ISS / AIS 等量表） | | ZYOverflowTooltip | 文本溢出时自动 Tooltip 提示 | | ZYIconButton | 带延迟显示 Tooltip 的图标按钮 |

Hooks

全局上下文

| Hook | 说明 | | -------------------- | ---------------------------------------------------------------- | | useGlobalConfig() | 读取 { projectId, eventId }（自动从 provide 链或全局单例获取） | | useGlobalRequest() | 读取注入的 axios 实例 | | useGlobalStorage() | 获取全局共享存储的 dataStructure / searchConfig 响应式引用 |

业务存储

| Hook | 说明 | | ------------------------- | ------------------------------------------------------------------------------------------------------------- | | useDataStructureStore() | 提供 getDataStructure(params, options)，含缓存 | | useSearchConfigStore() | 提供 getSearchConfigData / updateSearches / deleteSearches / clearSearchConfigCache，内部串行异步队列 | | useCustomizedExport() | 提供 getExportTemplateList |

工具 Hooks

| Hook | 说明 | | ----------------------------------------------- | ------------------------------------------------ | | useElementSize(target) | 监听元素尺寸变化，返回响应式 { width, height } | | useAsyncQueue(fn) / useSeniorAsyncQueue(fn) | 串行异步任务队列 |

工具函数（Utils）

| 函数 | 说明 | | ------------------------------------------- | --------------------------------------------- | | withInstall(comp, extra?) | 为 SFC 添加 install 方法 | | transferMapToOptions(map, isValueNumber?) | { a: 'A' } → [{ value: 'a', label: 'A' }] | | mergeRecursive(obj1, obj2) | 递归合并对象（双数组拼接） | | encodeSearchKey(key) | URL 特殊字符转义（% ? # & =） | | transferNumberToPx(value) | 10 → '10px'，字符串原样返回 | | getTimestampStr() | 当前时间戳字符串 |

Service 层

内置一组与后端约定的接口封装，自动注入 projectId / eventId：

| 函数 | 用途 | | ----------------------------------------------------------------------- | -------------------------- | | getSearchableFields | 获取可检索字段（数据结构） | | getSearchConfig | 获取用户检索表单配置 | | updateSearches / deleteSearches | 增删用户自定义检索条件 | | updateColumns / deleteColumns | 增删用户自定义列 | | getExportTemplateList / saveExportTemplate / deleteExportTemplate | 导出模板管理 | | getQueryTemplateList / saveQueryTemplate / deleteQueryTemplate | 高级检索模板管理 | | getFieldOptions | 获取字段候选项（带分页） |

接口地址通过 api 常量统一管理，可按需覆盖。

全局配置 Props

ZYGlobalProvider / provideGlobalConfig 接收以下 props：

| Prop | 类型 | 说明 | | ------------------ | ----------------------------------- | --------------------------------------------- | | request | AxiosInstance | 全局请求实例（仅 ZYGlobalProvider 的 prop） | | projectId | string \| number | 静态项目 ID | | eventId | string \| number | 静态事件 ID | | getProjectId | () => string \| number | 动态获取项目 ID（优先级低于 projectId） | | getEventId | () => string \| number | 动态获取事件 ID | | getDataStructure | (args) => Promise<any[]> \| any[] | 自定义数据结构获取函数 |

projectId / eventId 的解析规则：优先使用静态值；静态值为空时回退到 getter；均未提供时回退到 -1。0 视为合法值。

开发

# 安装依赖（在仓库根目录）
pnpm install

# 进入包目录
cd packages/business

# 类型检查
npm run type-check

# 构建
npm run build

# 单元测试
npm run test:unit

# Lint
npm run lint

License

MIT