@hbdlzy/ui-core 0.1.0 → 0.1.1

package/src/components/BaseEChart/BaseEChart.vue

@@ -0,0 +1,327 @@
+<template>
+  <div ref="containerRef" class="base-echart">
+    <div ref="chartRef" class="base-echart__inner"></div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { nextTick, onMounted, onUnmounted, ref, shallowRef, watch } from 'vue'
+import { echarts } from '../../echarts'
+import type {
+  EChartInitOptions,
+  EChartInstance,
+  EChartLoadingOptions,
+  EChartOption,
+  EChartResizeOptions,
+  EChartSetOptionOptions
+} from '../../echarts'
+import type { BaseEChartExpose, BaseEChartProps } from './BaseEChart.types'
+
+const props = withDefaults(defineProps<BaseEChartProps>(), {
+  option: () => ({}),
+  initOptions: () => ({ renderer: 'canvas' } as EChartInitOptions),
+  setOptionOptions: () => ({ notMerge: false, lazyUpdate: true } as EChartSetOptionOptions),
+  loading: false,
+  autoResize: true,
+  useDefaultColors: true,
+  colorStorageKey: 'echartsColor',
+  defaultColors: () => [],
+  group: undefined
+})
+
+const emit = defineEmits<{
+  (event: 'ready', chart: EChartInstance): void
+}>()
+
+const containerRef = ref<HTMLElement | null>(null)
+const chartRef = ref<HTMLElement | null>(null)
+const chartInstance = shallowRef<EChartInstance | null>(null)
+
+let resizeObserver: ResizeObserver | null = null
+let resizeFrameId: number | null = null
+let pendingResizeOptions: EChartResizeOptions | undefined
+
+const cancelResizeFrame = () => {
+  if (resizeFrameId !== null) {
+    cancelAnimationFrame(resizeFrameId)
+    resizeFrameId = null
+  }
+}
+
+const getDefaultColors = () => {
+  if (!props.useDefaultColors || typeof window === 'undefined') {
+    return props.defaultColors
+  }
+
+  try {
+    const raw = window.sessionStorage.getItem(props.colorStorageKey)
+    const colors = raw ? (JSON.parse(raw) as string[]) : []
+    return colors.length > 0 ? colors : props.defaultColors
+  } catch {
+    return props.defaultColors
+  }
+}
+
+const normalizeOption = (option: EChartOption = {}) => {
+  if (option.color) {
+    return option
+  }
+
+  const colors = getDefaultColors()
+  if (!colors || colors.length === 0) {
+    return option
+  }
+
+  return {
+    ...option,
+    color: colors
+  }
+}
+
+const createChart = () => {
+  if (!chartRef.value) {
+    return null
+  }
+
+  const existingChart = echarts.getInstanceByDom(chartRef.value)
+  existingChart?.dispose()
+
+  const instance = echarts.init(chartRef.value, props.theme, props.initOptions)
+  if (props.group) {
+    instance.group = props.group
+  }
+
+  chartInstance.value = instance
+  emit('ready', instance)
+  return instance
+}
+
+const getInstance = () => chartInstance.value
+
+const ensureChart = () => chartInstance.value ?? createChart()
+
+const setOption = (
+  option: EChartOption,
+  setOptionOptions: boolean | EChartSetOptionOptions = props.setOptionOptions
+) => {
+  const chart = ensureChart()
+  if (!chart) {
+    return null
+  }
+
+  const nextOption = normalizeOption(option)
+  if (typeof setOptionOptions === 'boolean') {
+    chart.setOption(nextOption, setOptionOptions)
+  } else {
+    chart.setOption(nextOption, setOptionOptions)
+  }
+
+  return chart
+}
+
+const showLoading = (type = 'default', loadingOptions?: EChartLoadingOptions) => {
+  const chart = ensureChart()
+  if (!chart) {
+    return
+  }
+
+  chart.showLoading(type, loadingOptions)
+}
+
+const hideLoading = () => {
+  chartInstance.value?.hideLoading()
+}
+
+const syncLoading = () => {
+  if (props.loading) {
+    showLoading('default', props.loadingOptions)
+    return
+  }
+
+  hideLoading()
+}
+
+const resize = (resizeOptions?: EChartResizeOptions) => {
+  pendingResizeOptions = resizeOptions
+  cancelResizeFrame()
+
+  resizeFrameId = requestAnimationFrame(() => {
+    chartInstance.value?.resize(pendingResizeOptions)
+    pendingResizeOptions = undefined
+    resizeFrameId = null
+  })
+}
+
+const handleWindowResize = () => {
+  resize()
+}
+
+const stopAutoResize = () => {
+  resizeObserver?.disconnect()
+  resizeObserver = null
+  window.removeEventListener('resize', handleWindowResize)
+}
+
+const startAutoResize = () => {
+  stopAutoResize()
+
+  if (!props.autoResize || !containerRef.value) {
+    return
+  }
+
+  resizeObserver = new ResizeObserver(() => {
+    resize()
+  })
+  resizeObserver.observe(containerRef.value)
+  window.addEventListener('resize', handleWindowResize)
+}
+
+const clear = () => {
+  chartInstance.value?.clear()
+}
+
+const disposeChart = () => {
+  chartInstance.value?.dispose()
+  chartInstance.value = null
+}
+
+const dispose = () => {
+  disposeChart()
+}
+
+const dispatchAction = (payload: Record<string, unknown>) => {
+  chartInstance.value?.dispatchAction(payload as never)
+}
+
+const on = (eventName: string, handler: (...args: any[]) => void, context?: unknown) => {
+  const chart = ensureChart()
+  chart?.on(eventName, handler, context)
+}
+
+const off = (eventName?: string, handler?: (...args: any[]) => void) => {
+  if (!chartInstance.value) {
+    return
+  }
+
+  if (!eventName) {
+    chartInstance.value.off()
+    return
+  }
+
+  if (handler) {
+    chartInstance.value.off(eventName, handler)
+    return
+  }
+
+  chartInstance.value.off(eventName)
+}
+
+const reinitChart = async () => {
+  disposeChart()
+  await nextTick()
+  createChart()
+  setOption(props.option)
+  syncLoading()
+  resize()
+}
+
+watch(
+  () => props.option,
+  option => {
+    setOption(option)
+  },
+  { deep: true }
+)
+
+watch(
+  () => props.loading,
+  () => {
+    syncLoading()
+  }
+)
+
+watch(
+  () => props.loadingOptions,
+  () => {
+    if (props.loading) {
+      syncLoading()
+    }
+  },
+  { deep: true }
+)
+
+watch(
+  () => props.group,
+  group => {
+    if (!chartInstance.value) {
+      return
+    }
+
+    chartInstance.value.group = group ?? ''
+  }
+)
+
+watch(
+  () => props.autoResize,
+  async enabled => {
+    stopAutoResize()
+    if (enabled) {
+      await nextTick()
+      startAutoResize()
+      resize()
+    }
+  }
+)
+
+watch(
+  () => props.theme,
+  () => {
+    reinitChart()
+  },
+  { deep: true }
+)
+
+watch(
+  () => props.initOptions,
+  () => {
+    reinitChart()
+  },
+  { deep: true }
+)
+
+onMounted(async () => {
+  await nextTick()
+  createChart()
+  setOption(props.option)
+  syncLoading()
+  startAutoResize()
+  resize()
+})
+
+onUnmounted(() => {
+  stopAutoResize()
+  cancelResizeFrame()
+  disposeChart()
+})
+
+defineExpose<BaseEChartExpose>({
+  getInstance,
+  setOption,
+  resize,
+  dispatchAction,
+  showLoading,
+  hideLoading,
+  clear,
+  dispose,
+  on,
+  off
+})
+</script>
+
+<style scoped>
+.base-echart,
+.base-echart__inner {
+  width: 100%;
+  height: 100%;
+}
+</style>

package/src/components/BaseEChart/README.md

@@ -0,0 +1,136 @@
+# BaseEChart
+
+`BaseEChart` 用来统一封装项目里重复出现的 ECharts 初始化、更新、尺寸监听和实例销毁逻辑。
+
+## 解决的问题
+
+- 页面只传 `option` 就能渲染图表
+- 自动处理 `init`、`setOption`、`resize`、`dispose`
+- 容器尺寸变化时自动 `resize`
+- 不传 `color` 时自动读取 `sessionStorage.echartsColor`
+- 需要手动控制时，可以直接通过组件实例调用 ECharts 方法
+
+## 适用场景
+
+- 大部分常规图表页面
+- 希望页面层只维护 `option`
+- 需要统一收敛图表的生命周期代码
+- 需要在页面层偶尔调用 `resize`、`dispatchAction`、`showLoading`
+
+## 不适用场景
+
+- 需要完全接管图表 DOM 生命周期
+- 需要自定义复杂容器交互且不适合组件封装
+- 单个页面里要做强定制图表引擎适配
+
+## 基础用法
+
+父容器必须有明确高度。
+
+```vue
+<template>
+  <div style="height: 320px">
+    <BaseEChart :option="option" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { BaseEChart, echarts, type EChartOption } from '@hbdlzy/ui-core'
+
+const option: EChartOption = {
+  tooltip: {
+    trigger: 'axis'
+  },
+  xAxis: {
+    type: 'category',
+    data: ['01', '02', '03']
+  },
+  yAxis: {
+    type: 'value'
+  },
+  series: [
+    {
+      type: 'line',
+      smooth: true,
+      data: [12, 18, 15],
+      areaStyle: {
+        color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
+          { offset: 0, color: 'rgba(24, 144, 255, 0.35)' },
+          { offset: 1, color: 'rgba(24, 144, 255, 0)' }
+        ])
+      }
+    }
+  ]
+}
+</script>
+```
+
+## 直接调用实例方法
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { BaseEChart, type BaseEChartExpose } from '@hbdlzy/ui-core'
+
+const chartRef = ref<BaseEChartExpose | null>(null)
+
+const refreshChart = () => {
+  chartRef.value?.resize()
+  chartRef.value?.dispatchAction({
+    type: 'hideTip'
+  })
+}
+</script>
+
+<template>
+  <BaseEChart ref="chartRef" :option="option" />
+</template>
+```
+
+## 直接调用 echarts 原生能力
+
+```ts
+import { echarts } from '@hbdlzy/ui-core'
+
+const gradient = new echarts.graphic.LinearGradient(0, 0, 0, 1, [
+  { offset: 0, color: '#2f88ff' },
+  { offset: 1, color: 'rgba(47, 136, 255, 0)' }
+])
+```
+
+## Props
+
+- `option`: 图表配置，直接透传给 `setOption`
+- `theme`: ECharts 主题
+- `initOptions`: `echarts.init` 的第三个参数
+- `setOptionOptions`: `setOption` 的第二个参数
+- `loading`: 是否显示 loading
+- `loadingOptions`: loading 配置
+- `autoResize`: 是否自动监听尺寸变化并执行 `resize`
+- `useDefaultColors`: 当 `option.color` 未传时，是否自动读取默认配色
+- `colorStorageKey`: 默认配色的 `sessionStorage` key，默认 `echartsColor`
+- `defaultColors`: 默认配色兜底值
+- `group`: 图表联动分组
+
+## Events
+
+- `ready`: 图表实例初始化完成时触发，返回 ECharts 实例
+
+## Expose
+
+- `getInstance`: 获取当前 ECharts 实例
+- `setOption`: 手动设置 option
+- `resize`: 手动触发 resize
+- `dispatchAction`: 调用原生 `dispatchAction`
+- `showLoading`: 显示 loading
+- `hideLoading`: 隐藏 loading
+- `clear`: 清空图表
+- `dispose`: 销毁图表实例
+- `on`: 绑定 ECharts 事件
+- `off`: 解绑 ECharts 事件
+
+## 推荐约定
+
+- 页面层只维护 `option`，不要重复写 `echarts.init`
+- 默认走 `BaseEChart + option`，只有确实需要时再通过 `ref` 调暴露方法
+- 渐变色、图形工具优先从 `@hbdlzy/ui-core` 导出的 `echarts` 使用

package/src/components/BaseEChart/index.ts

@@ -0,0 +1,5 @@
+import BaseEChart from './BaseEChart.vue'
+
+export default BaseEChart
+
+export type { BaseEChartExpose, BaseEChartProps } from './BaseEChart.types'

package/src/components/BaseExportButton/BaseExportButton.vue

@@ -140,7 +140,7 @@ async function handleExport() {
 
   try {
     if (exportMode.value === 'excel' && props.excelOptions) {
-      exportExcel(props.excelOptions)
+      await exportExcel(props.excelOptions)
 
       if (props.autoMessage) {
         ElMessage.success(props.successMessage)

package/src/components/BaseExportButton/README.md

@@ -1,25 +1,121 @@
 # BaseExportButton
 
-`BaseExportButton` 是一个基础导出按钮组件，用来统一项目里的导出入口。
+`BaseExportButton` 用来统一项目中的导出入口，避免每个页面重复写按钮状态、导出前校验、成功失败提示和文件下载逻辑。
 
-它支持两类场景：
+## 解决的问题
 
-- 纯前端 Excel 导出
-- 调接口返回 blob 文件下载
+- 统一前端 Excel 导出按钮交互
+- 统一后端 `blob` 文件下载按钮交互
+- 自动处理 loading 状态
+- 自动处理成功和失败消息提示
+- 将导出前校验、导出成功回调收敛成统一接口
 
-## 使用方式
+## 适用场景
+
+- 页面需要导出表格数据为 Excel
+- 页面需要调用后端接口导出文件
+- 希望多个项目中的导出按钮交互保持一致
+
+## 不适用场景
+
+- 页面需要复杂的导出配置弹窗
+- 导出前需要强业务表单流程编排
+- 不是按钮触发型的导出入口
+
+## 支持模式
+
+- `excelOptions`: 纯前端 Excel 导出
+- `requestHandler`: 调接口获取 `blob` 或二进制响应后下载
+
+这两个模式二选一，不能同时传。
+
+## 基础用法
 
 ```vue
+<template>
+  <BaseExportButton :excel-options="excelOptions" />
+</template>
+
 <script setup lang="ts">
-import { BaseExportButton } from '@hbdlzy/ui-core'
+import { BaseExportButton, type ExcelExportOptions } from '@hbdlzy/ui-core'
+
+interface UserRow {
+  name: string
+  department: string
+}
+
+const excelOptions: ExcelExportOptions<UserRow> = {
+  fileName: '用户列表',
+  columns: [
+    { label: '姓名', key: 'name' },
+    { label: '部门', key: 'department' }
+  ],
+  data: [
+    { name: '张三', department: '运维' },
+    { name: '李四', department: '调度' }
+  ]
+}
 </script>
+```
+
+## 后端导出示例
 
+```vue
 <template>
-  <BaseExportButton :excel-options="excelOptions" />
+  <BaseExportButton
+    file-name="运行报表.xlsx"
+    :request-handler="requestHandler"
+    :before-export="beforeExport"
+  />
 </template>
+
+<script setup lang="ts">
+import { BaseExportButton } from '@hbdlzy/ui-core'
+
+const beforeExport = async () => {
+  return true
+}
+
+const requestHandler = async () => {
+  const response = await api.exportReport()
+
+  return {
+    data: response.data,
+    headers: response.headers
+  }
+}
+</script>
 ```
 
+## Props
+
+- `label`: 按钮文案，默认 `导出`
+- `type`: Element Plus 按钮类型，默认 `primary`
+- `size`: 按钮尺寸，默认 `default`
+- `plain`: 是否朴素按钮
+- `link`: 是否链接按钮
+- `text`: 是否文字按钮
+- `disabled`: 是否禁用
+- `fileName`: 后端下载时的兜底文件名
+- `excelOptions`: 前端 Excel 导出配置
+- `requestHandler`: 后端导出请求函数
+- `beforeExport`: 导出前钩子，返回 `false` 时中断导出
+- `successMessage`: 成功提示文案
+- `errorMessage`: 失败提示文案
+- `autoMessage`: 是否自动弹出成功失败提示
+
+## Events
+
+- `start`: 点击并通过校验后开始导出
+- `success`: 导出成功，返回 `{ mode, fileName }`
+- `error`: 导出失败
+
 ## 约束
 
 - `excelOptions` 和 `requestHandler` 二选一
-- 组件只负责触发导出，不负责业务数据查询
+- 组件只负责触发导出，不负责业务数据查询
+- 如果使用前端导出，建议优先复用 `exportExcel`
+
+## 相关能力
+
+- 工具函数：`@hbdlzy/ui-core` 中的 `exportExcel`