@hbdlzy/ui-core 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @hbdlzy/ui-core
+
+`@hbdlzy/ui-core` 负责沉淀跨项目复用的基础 UI 组件和无业务依赖的前端工具。
+
+## 当前内容
+
+- `BaseExportButton`
+- `exportExcel`
+
+## 使用方式
+
+```ts
+import { BaseExportButton, exportExcel } from '@hbdlzy/ui-core'
+```
+
+## 设计原则
+
+- 只做基础 UI 和交互
+- 不直接依赖接口、路由、store
+- 每个组件必须配套 README 和 AI manifest

package/components.manifest.json

@@ -0,0 +1,50 @@
+{
+  "package": "@hbdlzy/ui-core",
+  "version": 1,
+  "updatedAt": "2026-04-21",
+  "components": [
+    {
+      "name": "BaseExportButton",
+      "category": "ui-core",
+      "entry": "@hbdlzy/ui-core",
+      "importName": "BaseExportButton",
+      "docs": "packages/ui-core/src/components/BaseExportButton/README.md",
+      "description": "统一处理前端 Excel 导出和后�?blob 下载的基础导出按钮�?,
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": "导出"
+        },
+        {
+          "name": "fileName",
+          "type": "string",
+          "default": ""
+        },
+        {
+          "name": "excelOptions",
+          "type": "ExcelExportOptions",
+          "required": false
+        },
+        {
+          "name": "requestHandler",
+          "type": "() => Promise<ExportResponseLike>",
+          "required": false
+        },
+        {
+          "name": "beforeExport",
+          "type": "() => boolean | Promise<boolean>",
+          "required": false
+        }
+      ],
+      "emits": ["start", "success", "error"]
+    }
+  ],
+  "utilities": [
+    {
+      "name": "exportExcel",
+      "entry": "@hbdlzy/ui-core",
+      "description": "支持多级表头和自动列宽的纯前�?Excel 导出工具�?
+    }
+  ]
+}

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});var c=require("vue"),g=require("element-plus"),w=require("xlsx"),O=require("file-saver");function D(e){if(e&&e.__esModule)return e;var r=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});return e&&Object.keys(e).forEach(function(t){if(t!=="default"){var n=Object.getOwnPropertyDescriptor(e,t);Object.defineProperty(r,t,n.get?n:{enumerable:!0,get:function(){return e[t]}})}}),r.default=e,Object.freeze(r)}var x=D(w);const S="Sheet1",A=16;function h(e){var r;return(r=e.children)!=null&&r.length?e.children.reduce((t,n)=>t+h(n),0):1}function y(e,r=1){return e.reduce((t,n)=>{var o;return(o=n.children)!=null&&o.length?Math.max(t,y(n.children,r+1)):Math.max(t,r)},r)}function b(e){const r=`${e!=null?e:""}`;return Array.from(r).reduce((t,n)=>t+(n.charCodeAt(0)>255?2:1),0)}function _(e,r){return r?r.split(".").reduce((t,n)=>{if(t!=null)return t[n]},e):""}function N(e,r,t){return typeof t.formatter=="function"?t.formatter(e,r,t):_(e,t.key)}function q(e){const r=y(e),t=e.reduce((u,s)=>u+h(s),0),n=Array.from({length:r},()=>Array.from({length:t}).fill("")),o=[],l=[];let f=0;const d=(u,s)=>{var p;const a=f,i=h(u);if(n[s][a]=u.label,(p=u.children)!=null&&p.length){u.children.forEach(m=>d(m,s+1)),i>1&&o.push({s:{r:s,c:a},e:{r:s,c:a+i-1}});return}l.push(u),f+=1,s<r-1&&o.push({s:{r:s,c:a},e:{r:r-1,c:a}})};return e.forEach(u=>d(u,0)),{headerRows:n,leafColumns:l,merges:o}}function H(e,r,t,n){return e.map((o,l)=>{var s;const f=b(o.label),d=r.reduce((a,i)=>Math.max(a,b(i[l])),0);return{wch:(s=o.width)!=null?s:n?Math.max(t,f,d):t}})}function k(e){return e.endsWith(".xlsx")?e:`${e}.xlsx`}function F(e){const{fileName:r,sheetName:t=S,data:n,autoWidth:o=!0,defaultColumnWidth:l=A}=e,f=e.columns.filter(m=>!!m);if(!f.length)throw new Error("Excel export columns can not be empty.");const{headerRows:d,leafColumns:u,merges:s}=q(f),a=n.map((m,B)=>u.map(M=>N(m,B,M))),i=x.utils.aoa_to_sheet([...d,...a]);i["!merges"]=s,i["!cols"]=H(u,a,l,o);const p=x.utils.book_new();x.utils.book_append_sheet(p,i,t),x.writeFile(p,k(r))}const L="export-file";function z(e,r){var o;if(!e)return"";const t=r.toLowerCase(),n=Object.keys(e).find(l=>l.toLowerCase()===t);return n&&(o=e[n])!=null?o:""}function C(e){if(!e)return"";const r=e.match(/filename\*=UTF-8''([^;]+)/i);if(r!=null&&r[1])return decodeURIComponent(r[1].replace(/["']/g,""));const t=e.match(/filename="?([^";]+)"?/i);return t!=null&&t[1]?decodeURIComponent(t[1].replace(/["']/g,"")):""}function E(e){return`${e!=null?e:""}`.trim()||L}function T(e){return e instanceof Blob?e:new Blob([e])}function v(e,r=""){const t=z(e.headers,"content-disposition"),n=E(C(t)||r);return O.saveAs(T(e.data),n),n}const j=c.defineComponent({__name:"BaseExportButton",props:{label:{type:String,default:"\u5BFC\u51FA"},type:{type:String,default:"primary"},size:{type:String,default:"default"},plain:{type:Boolean,default:!1},link:{type:Boolean,default:!1},text:{type:Boolean,default:!1},disabled:{type:Boolean,default:!1},fileName:{type:String,default:""},excelOptions:Object,requestHandler:Function,beforeExport:Function,successMessage:{type:String,default:"\u5BFC\u51FA\u6210\u529F"},errorMessage:{type:String,default:"\u5BFC\u51FA\u5931\u8D25\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5"},autoMessage:{type:Boolean,default:!0}},emits:["start","success","error"],setup(e,{emit:r}){const t=e,n=r,o=c.ref(!1),l=c.computed(()=>t.excelOptions&&t.requestHandler?"invalid":t.excelOptions?"excel":t.requestHandler?"request":"none"),f=c.computed(()=>t.disabled||o.value||l.value==="none");async function d(){return t.beforeExport?await t.beforeExport()!==!1:!0}async function u(){if(o.value||t.disabled)return;if(l.value==="none"){g.ElMessage.warning("\u8BF7\u5148\u914D\u7F6E\u5BFC\u51FA\u903B\u8F91");return}if(l.value==="invalid"){const a=new Error("BaseExportButton \u4E0D\u80FD\u540C\u65F6\u63A5\u6536 excelOptions \u548C requestHandler");n("error",a),g.ElMessage.error(a.message);return}if(!!await d()){o.value=!0,n("start");try{if(l.value==="excel"&&t.excelOptions){F(t.excelOptions),t.autoMessage&&g.ElMessage.success(t.successMessage),n("success",{mode:"excel",fileName:E(t.excelOptions.fileName)});return}if(l.value==="request"&&t.requestHandler){const a=await t.requestHandler(),i=v(a,t.fileName);t.autoMessage&&g.ElMessage.success(t.successMessage),n("success",{mode:"request",fileName:i})}}catch(a){console.error(a),t.autoMessage&&g.ElMessage.error(t.errorMessage),n("error",a)}finally{o.value=!1}}}return(s,a)=>{const i=c.resolveComponent("el-button");return c.openBlock(),c.createBlock(i,{class:"base-export-button",type:e.type,size:e.size,plain:e.plain,link:e.link,text:e.text,disabled:f.value,loading:o.value,onClick:u},{default:c.withCtx(()=>[c.renderSlot(s.$slots,"default",{},()=>[c.createTextVNode(c.toDisplayString(e.label),1)])]),_:3},8,["type","size","plain","link","text","disabled","loading"])}}});exports.BaseExportButton=j;exports.downloadExportResponse=v;exports.exportExcel=F;exports.extractFileNameFromDisposition=C;exports.normalizeExportFileName=E;

package/dist/index.js

@@ -0,0 +1,308 @@
+import { defineComponent, ref, computed, resolveComponent, openBlock, createBlock, withCtx, renderSlot, createTextVNode, toDisplayString } from "vue";
+import { ElMessage } from "element-plus";
+import * as XLSX from "xlsx";
+import { saveAs } from "file-saver";
+const DEFAULT_SHEET_NAME = "Sheet1";
+const DEFAULT_COLUMN_WIDTH = 16;
+function getLeafCount(column) {
+  var _a;
+  if (!((_a = column.children) == null ? void 0 : _a.length)) {
+    return 1;
+  }
+  return column.children.reduce((count, child) => count + getLeafCount(child), 0);
+}
+function getMaxDepth(columns, depth = 1) {
+  return columns.reduce((maxDepth, column) => {
+    var _a;
+    if (!((_a = column.children) == null ? void 0 : _a.length)) {
+      return Math.max(maxDepth, depth);
+    }
+    return Math.max(maxDepth, getMaxDepth(column.children, depth + 1));
+  }, depth);
+}
+function getDisplayLength(value) {
+  const text = `${value != null ? value : ""}`;
+  return Array.from(text).reduce((length, char) => {
+    return length + (char.charCodeAt(0) > 255 ? 2 : 1);
+  }, 0);
+}
+function getValueByPath(source, path) {
+  if (!path) {
+    return "";
+  }
+  return path.split(".").reduce((current, key) => {
+    if (current === null || current === void 0) {
+      return void 0;
+    }
+    return current[key];
+  }, source);
+}
+function getCellValue(row, rowIndex, column) {
+  if (typeof column.formatter === "function") {
+    return column.formatter(row, rowIndex, column);
+  }
+  return getValueByPath(row, column.key);
+}
+function buildHeaderMatrix(columns) {
+  const maxDepth = getMaxDepth(columns);
+  const totalLeafCount = columns.reduce((count, column) => count + getLeafCount(column), 0);
+  const headerRows = Array.from({ length: maxDepth }, () => Array.from({ length: totalLeafCount }).fill(""));
+  const merges = [];
+  const leafColumns = [];
+  let currentColumnIndex = 0;
+  const fillHeaders = (column, depth) => {
+    var _a;
+    const startColumnIndex = currentColumnIndex;
+    const leafCount = getLeafCount(column);
+    headerRows[depth][startColumnIndex] = column.label;
+    if ((_a = column.children) == null ? void 0 : _a.length) {
+      column.children.forEach((child) => fillHeaders(child, depth + 1));
+      if (leafCount > 1) {
+        merges.push({
+          s: { r: depth, c: startColumnIndex },
+          e: { r: depth, c: startColumnIndex + leafCount - 1 }
+        });
+      }
+      return;
+    }
+    leafColumns.push(column);
+    currentColumnIndex += 1;
+    if (depth < maxDepth - 1) {
+      merges.push({
+        s: { r: depth, c: startColumnIndex },
+        e: { r: maxDepth - 1, c: startColumnIndex }
+      });
+    }
+  };
+  columns.forEach((column) => fillHeaders(column, 0));
+  return {
+    headerRows,
+    leafColumns,
+    merges
+  };
+}
+function buildColumnWidths(leafColumns, dataRows, defaultColumnWidth, autoWidth) {
+  return leafColumns.map((column, columnIndex) => {
+    var _a;
+    const headerWidth = getDisplayLength(column.label);
+    const dataWidth = dataRows.reduce((maxWidth, row) => {
+      return Math.max(maxWidth, getDisplayLength(row[columnIndex]));
+    }, 0);
+    const targetWidth = (_a = column.width) != null ? _a : autoWidth ? Math.max(defaultColumnWidth, headerWidth, dataWidth) : defaultColumnWidth;
+    return { wch: targetWidth };
+  });
+}
+function normalizeFileName(fileName) {
+  return fileName.endsWith(".xlsx") ? fileName : `${fileName}.xlsx`;
+}
+function exportExcel(options) {
+  const {
+    fileName,
+    sheetName = DEFAULT_SHEET_NAME,
+    data,
+    autoWidth = true,
+    defaultColumnWidth = DEFAULT_COLUMN_WIDTH
+  } = options;
+  const columns = options.columns.filter((column) => !!column);
+  if (!columns.length) {
+    throw new Error("Excel export columns can not be empty.");
+  }
+  const { headerRows, leafColumns, merges } = buildHeaderMatrix(columns);
+  const dataRows = data.map((row, rowIndex) => leafColumns.map((column) => getCellValue(row, rowIndex, column)));
+  const worksheet = XLSX.utils.aoa_to_sheet([...headerRows, ...dataRows]);
+  worksheet["!merges"] = merges;
+  worksheet["!cols"] = buildColumnWidths(leafColumns, dataRows, defaultColumnWidth, autoWidth);
+  const workbook = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(workbook, worksheet, sheetName);
+  XLSX.writeFile(workbook, normalizeFileName(fileName));
+}
+const DEFAULT_EXPORT_FILE_NAME = "export-file";
+function getHeaderValue(headers, headerName) {
+  var _a;
+  if (!headers) {
+    return "";
+  }
+  const targetHeaderName = headerName.toLowerCase();
+  const matchedHeaderKey = Object.keys(headers).find((key) => key.toLowerCase() === targetHeaderName);
+  return matchedHeaderKey ? (_a = headers[matchedHeaderKey]) != null ? _a : "" : "";
+}
+function extractFileNameFromDisposition(contentDisposition) {
+  if (!contentDisposition) {
+    return "";
+  }
+  const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i);
+  if (utf8Match == null ? void 0 : utf8Match[1]) {
+    return decodeURIComponent(utf8Match[1].replace(/["']/g, ""));
+  }
+  const basicMatch = contentDisposition.match(/filename="?([^";]+)"?/i);
+  if (basicMatch == null ? void 0 : basicMatch[1]) {
+    return decodeURIComponent(basicMatch[1].replace(/["']/g, ""));
+  }
+  return "";
+}
+function normalizeExportFileName(fileName) {
+  const normalizedFileName = `${fileName != null ? fileName : ""}`.trim();
+  return normalizedFileName || DEFAULT_EXPORT_FILE_NAME;
+}
+function toBlob(payload) {
+  return payload instanceof Blob ? payload : new Blob([payload]);
+}
+function downloadExportResponse(response, fallbackFileName = "") {
+  const contentDisposition = getHeaderValue(response.headers, "content-disposition");
+  const fileName = normalizeExportFileName(extractFileNameFromDisposition(contentDisposition) || fallbackFileName);
+  saveAs(toBlob(response.data), fileName);
+  return fileName;
+}
+const _sfc_main = defineComponent({
+  __name: "BaseExportButton",
+  props: {
+    label: {
+      type: String,
+      default: "\u5BFC\u51FA"
+    },
+    type: {
+      type: String,
+      default: "primary"
+    },
+    size: {
+      type: String,
+      default: "default"
+    },
+    plain: {
+      type: Boolean,
+      default: false
+    },
+    link: {
+      type: Boolean,
+      default: false
+    },
+    text: {
+      type: Boolean,
+      default: false
+    },
+    disabled: {
+      type: Boolean,
+      default: false
+    },
+    fileName: {
+      type: String,
+      default: ""
+    },
+    excelOptions: Object,
+    requestHandler: Function,
+    beforeExport: Function,
+    successMessage: {
+      type: String,
+      default: "\u5BFC\u51FA\u6210\u529F"
+    },
+    errorMessage: {
+      type: String,
+      default: "\u5BFC\u51FA\u5931\u8D25\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5"
+    },
+    autoMessage: {
+      type: Boolean,
+      default: true
+    }
+  },
+  emits: ["start", "success", "error"],
+  setup(__props, { emit: __emit }) {
+    const props = __props;
+    const emit = __emit;
+    const loading = ref(false);
+    const exportMode = computed(() => {
+      if (props.excelOptions && props.requestHandler) {
+        return "invalid";
+      }
+      if (props.excelOptions) {
+        return "excel";
+      }
+      if (props.requestHandler) {
+        return "request";
+      }
+      return "none";
+    });
+    const isDisabled = computed(() => props.disabled || loading.value || exportMode.value === "none");
+    async function runBeforeExport() {
+      if (!props.beforeExport) {
+        return true;
+      }
+      const result = await props.beforeExport();
+      return result !== false;
+    }
+    async function handleExport() {
+      if (loading.value || props.disabled) {
+        return;
+      }
+      if (exportMode.value === "none") {
+        ElMessage.warning("\u8BF7\u5148\u914D\u7F6E\u5BFC\u51FA\u903B\u8F91");
+        return;
+      }
+      if (exportMode.value === "invalid") {
+        const conflictError = new Error("BaseExportButton \u4E0D\u80FD\u540C\u65F6\u63A5\u6536 excelOptions \u548C requestHandler");
+        emit("error", conflictError);
+        ElMessage.error(conflictError.message);
+        return;
+      }
+      const canContinue = await runBeforeExport();
+      if (!canContinue) {
+        return;
+      }
+      loading.value = true;
+      emit("start");
+      try {
+        if (exportMode.value === "excel" && props.excelOptions) {
+          exportExcel(props.excelOptions);
+          if (props.autoMessage) {
+            ElMessage.success(props.successMessage);
+          }
+          emit("success", {
+            mode: "excel",
+            fileName: normalizeExportFileName(props.excelOptions.fileName)
+          });
+          return;
+        }
+        if (exportMode.value === "request" && props.requestHandler) {
+          const response = await props.requestHandler();
+          const fileName = downloadExportResponse(response, props.fileName);
+          if (props.autoMessage) {
+            ElMessage.success(props.successMessage);
+          }
+          emit("success", {
+            mode: "request",
+            fileName
+          });
+        }
+      } catch (error) {
+        console.error(error);
+        if (props.autoMessage) {
+          ElMessage.error(props.errorMessage);
+        }
+        emit("error", error);
+      } finally {
+        loading.value = false;
+      }
+    }
+    return (_ctx, _cache) => {
+      const _component_el_button = resolveComponent("el-button");
+      return openBlock(), createBlock(_component_el_button, {
+        class: "base-export-button",
+        type: __props.type,
+        size: __props.size,
+        plain: __props.plain,
+        link: __props.link,
+        text: __props.text,
+        disabled: isDisabled.value,
+        loading: loading.value,
+        onClick: handleExport
+      }, {
+        default: withCtx(() => [
+          renderSlot(_ctx.$slots, "default", {}, () => [
+            createTextVNode(toDisplayString(__props.label), 1)
+          ])
+        ]),
+        _: 3
+      }, 8, ["type", "size", "plain", "link", "text", "disabled", "loading"]);
+    };
+  }
+});
+export { _sfc_main as BaseExportButton, downloadExportResponse, exportExcel, extractFileNameFromDisposition, normalizeExportFileName };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hbdlzy/ui-core",
+  "version": "0.1.0",
+  "description": "Company shared Vue UI core package.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hbdlzy/componentized-library.git",
+    "directory": "packages/ui-core"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./src/index.ts"
+    },
+    "./components.manifest.json": "./components.manifest.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "components.manifest.json"
+  ],
+  "peerDependencies": {
+    "element-plus": "^2.13.7",
+    "vue": "^3.5.14"
+  },
+  "dependencies": {
+    "file-saver": "2.0.5",
+    "xlsx": "^0.18.5"
+  },
+  "sideEffects": [
+    "**/*.css",
+    "**/*.vue"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "vite build"
+  }
+}

package/src/components/BaseExportButton/BaseExportButton.types.ts

@@ -0,0 +1,29 @@
+import type { ExcelExportOptions } from '../../excel/exportExcel'
+
+export interface ExportResponseHeaders {
+  [key: string]: string | undefined
+}
+
+export interface ExportResponseLike {
+  data: Blob | BlobPart | ArrayBuffer
+  headers?: ExportResponseHeaders
+}
+
+export type ExportRequestHandler = () => Promise<ExportResponseLike>
+
+export type ExportMode = 'excel' | 'request' | 'none' | 'invalid'
+
+export type ExportBeforeHandler = () => boolean | void | Promise<boolean | void>
+
+export interface ExportSuccessPayload {
+  mode: Exclude<ExportMode, 'none' | 'invalid'>
+  fileName?: string
+}
+
+export interface BaseExportExcelConfig<Row = Record<string, any>> {
+  excelOptions: ExcelExportOptions<Row>
+}
+
+export interface BaseExportRequestConfig {
+  requestHandler: ExportRequestHandler
+}

package/src/components/BaseExportButton/BaseExportButton.utils.ts

@@ -0,0 +1,54 @@
+import { saveAs } from 'file-saver'
+import type { ExportResponseHeaders, ExportResponseLike } from './BaseExportButton.types'
+
+const DEFAULT_EXPORT_FILE_NAME = 'export-file'
+
+function getHeaderValue(headers: ExportResponseHeaders | undefined, headerName: string) {
+  if (!headers) {
+    return ''
+  }
+
+  const targetHeaderName = headerName.toLowerCase()
+  const matchedHeaderKey = Object.keys(headers).find(key => key.toLowerCase() === targetHeaderName)
+
+  return matchedHeaderKey ? headers[matchedHeaderKey] ?? '' : ''
+}
+
+export function extractFileNameFromDisposition(contentDisposition?: string) {
+  if (!contentDisposition) {
+    return ''
+  }
+
+  const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i)
+
+  if (utf8Match?.[1]) {
+    return decodeURIComponent(utf8Match[1].replace(/["']/g, ''))
+  }
+
+  const basicMatch = contentDisposition.match(/filename="?([^";]+)"?/i)
+
+  if (basicMatch?.[1]) {
+    return decodeURIComponent(basicMatch[1].replace(/["']/g, ''))
+  }
+
+  return ''
+}
+
+export function normalizeExportFileName(fileName?: string) {
+  const normalizedFileName = `${fileName ?? ''}`.trim()
+
+  return normalizedFileName || DEFAULT_EXPORT_FILE_NAME
+}
+
+function toBlob(payload: ExportResponseLike['data']) {
+  return payload instanceof Blob ? payload : new Blob([payload])
+}
+
+export function downloadExportResponse(response: ExportResponseLike, fallbackFileName = '') {
+  const contentDisposition = getHeaderValue(response.headers, 'content-disposition')
+  const fileName = normalizeExportFileName(extractFileNameFromDisposition(contentDisposition) || fallbackFileName)
+
+  saveAs(toBlob(response.data), fileName)
+
+  return fileName
+}

package/src/components/BaseExportButton/BaseExportButton.vue

@@ -0,0 +1,182 @@
+<template>
+  <el-button
+    class="base-export-button"
+    :type="type"
+    :size="size"
+    :plain="plain"
+    :link="link"
+    :text="text"
+    :disabled="isDisabled"
+    :loading="loading"
+    @click="handleExport"
+  >
+    <slot>{{ label }}</slot>
+  </el-button>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import type { PropType } from 'vue'
+import { ElMessage } from 'element-plus'
+import { exportExcel, type ExcelExportOptions } from '../../excel/exportExcel'
+import { downloadExportResponse, normalizeExportFileName } from './BaseExportButton.utils'
+import type {
+  ExportBeforeHandler,
+  ExportMode,
+  ExportRequestHandler,
+  ExportSuccessPayload
+} from './BaseExportButton.types'
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: '导出'
+  },
+  type: {
+    type: String as PropType<'primary' | 'success' | 'warning' | 'danger' | 'info' | ''>,
+    default: 'primary'
+  },
+  size: {
+    type: String as PropType<'large' | 'default' | 'small'>,
+    default: 'default'
+  },
+  plain: {
+    type: Boolean,
+    default: false
+  },
+  link: {
+    type: Boolean,
+    default: false
+  },
+  text: {
+    type: Boolean,
+    default: false
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  fileName: {
+    type: String,
+    default: ''
+  },
+  excelOptions: Object as PropType<ExcelExportOptions<Record<string, any>>>,
+  requestHandler: Function as PropType<ExportRequestHandler>,
+  beforeExport: Function as PropType<ExportBeforeHandler>,
+  successMessage: {
+    type: String,
+    default: '导出成功'
+  },
+  errorMessage: {
+    type: String,
+    default: '导出失败，请稍后重试'
+  },
+  autoMessage: {
+    type: Boolean,
+    default: true
+  }
+})
+
+const emit = defineEmits<{
+  (event: 'start'): void
+  (event: 'success', payload: ExportSuccessPayload): void
+  (event: 'error', error: unknown): void
+}>()
+
+const loading = ref(false)
+
+const exportMode = computed<ExportMode>(() => {
+  if (props.excelOptions && props.requestHandler) {
+    return 'invalid'
+  }
+
+  if (props.excelOptions) {
+    return 'excel'
+  }
+
+  if (props.requestHandler) {
+    return 'request'
+  }
+
+  return 'none'
+})
+
+const isDisabled = computed(() => props.disabled || loading.value || exportMode.value === 'none')
+
+async function runBeforeExport() {
+  if (!props.beforeExport) {
+    return true
+  }
+
+  const result = await props.beforeExport()
+  return result !== false
+}
+
+async function handleExport() {
+  if (loading.value || props.disabled) {
+    return
+  }
+
+  if (exportMode.value === 'none') {
+    ElMessage.warning('请先配置导出逻辑')
+    return
+  }
+
+  if (exportMode.value === 'invalid') {
+    const conflictError = new Error('BaseExportButton 不能同时接收 excelOptions 和 requestHandler')
+    emit('error', conflictError)
+    ElMessage.error(conflictError.message)
+    return
+  }
+
+  const canContinue = await runBeforeExport()
+
+  if (!canContinue) {
+    return
+  }
+
+  loading.value = true
+  emit('start')
+
+  try {
+    if (exportMode.value === 'excel' && props.excelOptions) {
+      exportExcel(props.excelOptions)
+
+      if (props.autoMessage) {
+        ElMessage.success(props.successMessage)
+      }
+
+      emit('success', {
+        mode: 'excel',
+        fileName: normalizeExportFileName(props.excelOptions.fileName)
+      })
+
+      return
+    }
+
+    if (exportMode.value === 'request' && props.requestHandler) {
+      const response = await props.requestHandler()
+      const fileName = downloadExportResponse(response, props.fileName)
+
+      if (props.autoMessage) {
+        ElMessage.success(props.successMessage)
+      }
+
+      emit('success', {
+        mode: 'request',
+        fileName
+      })
+    }
+  } catch (error) {
+    console.error(error)
+
+    if (props.autoMessage) {
+      ElMessage.error(props.errorMessage)
+    }
+
+    emit('error', error)
+  } finally {
+    loading.value = false
+  }
+}
+</script>

package/src/components/BaseExportButton/README.md

@@ -0,0 +1,25 @@
+# BaseExportButton
+
+`BaseExportButton` 是一个基础导出按钮组件，用来统一项目里的导出入口。
+
+它支持两类场景：
+
+- 纯前端 Excel 导出
+- 调接口返回 blob 文件下载
+
+## 使用方式
+
+```vue
+<script setup lang="ts">
+import { BaseExportButton } from '@hbdlzy/ui-core'
+</script>
+
+<template>
+  <BaseExportButton :excel-options="excelOptions" />
+</template>
+```
+
+## 约束
+
+- `excelOptions` 和 `requestHandler` 二选一
+- 组件只负责触发导出，不负责业务数据查询

package/src/components/BaseExportButton/index.ts

@@ -0,0 +1,20 @@
+import BaseExportButton from './BaseExportButton.vue'
+
+export { BaseExportButton }
+export {
+  downloadExportResponse,
+  extractFileNameFromDisposition,
+  normalizeExportFileName
+} from './BaseExportButton.utils'
+export type {
+  BaseExportExcelConfig,
+  BaseExportRequestConfig,
+  ExportBeforeHandler,
+  ExportMode,
+  ExportRequestHandler,
+  ExportResponseHeaders,
+  ExportResponseLike,
+  ExportSuccessPayload
+} from './BaseExportButton.types'
+
+export default BaseExportButton

package/src/excel/exportExcel.ts

@@ -0,0 +1,170 @@
+import * as XLSX from 'xlsx'
+
+export type ExcelCellValue = string | number | boolean | null | undefined | Date
+
+export interface ExcelExportColumn<Row = Record<string, any>> {
+  label: string
+  key?: string
+  width?: number
+  formatter?: (row: Row, rowIndex: number, column: ExcelExportColumn<Row>) => ExcelCellValue
+  children?: Array<ExcelExportColumn<Row>>
+}
+
+export interface ExcelExportOptions<Row = Record<string, any>> {
+  fileName: string
+  sheetName?: string
+  columns: Array<ExcelExportColumn<Row>>
+  data: Array<Row>
+  autoWidth?: boolean
+  defaultColumnWidth?: number
+}
+
+const DEFAULT_SHEET_NAME = 'Sheet1'
+const DEFAULT_COLUMN_WIDTH = 16
+
+function getLeafCount<Row>(column: ExcelExportColumn<Row>): number {
+  if (!column.children?.length) {
+    return 1
+  }
+
+  return column.children.reduce((count, child) => count + getLeafCount(child), 0)
+}
+
+function getMaxDepth<Row>(columns: Array<ExcelExportColumn<Row>>, depth = 1): number {
+  return columns.reduce((maxDepth, column) => {
+    if (!column.children?.length) {
+      return Math.max(maxDepth, depth)
+    }
+
+    return Math.max(maxDepth, getMaxDepth(column.children, depth + 1))
+  }, depth)
+}
+
+function getDisplayLength(value: ExcelCellValue): number {
+  const text = `${value ?? ''}`
+
+  return Array.from(text).reduce((length, char) => {
+    return length + (char.charCodeAt(0) > 255 ? 2 : 1)
+  }, 0)
+}
+
+function getValueByPath(source: Record<string, any>, path?: string): ExcelCellValue {
+  if (!path) {
+    return ''
+  }
+
+  return path.split('.').reduce<any>((current, key) => {
+    if (current === null || current === undefined) {
+      return undefined
+    }
+
+    return current[key]
+  }, source)
+}
+
+function getCellValue<Row>(row: Row, rowIndex: number, column: ExcelExportColumn<Row>): ExcelCellValue {
+  if (typeof column.formatter === 'function') {
+    return column.formatter(row, rowIndex, column)
+  }
+
+  return getValueByPath(row as Record<string, any>, column.key)
+}
+
+function buildHeaderMatrix<Row>(columns: Array<ExcelExportColumn<Row>>) {
+  const maxDepth = getMaxDepth(columns)
+  const totalLeafCount = columns.reduce((count, column) => count + getLeafCount(column), 0)
+  const headerRows = Array.from({ length: maxDepth }, () => Array.from({ length: totalLeafCount }).fill(''))
+  const merges: XLSX.Range[] = []
+  const leafColumns: Array<ExcelExportColumn<Row>> = []
+
+  let currentColumnIndex = 0
+
+  const fillHeaders = (column: ExcelExportColumn<Row>, depth: number) => {
+    const startColumnIndex = currentColumnIndex
+    const leafCount = getLeafCount(column)
+
+    headerRows[depth][startColumnIndex] = column.label
+
+    if (column.children?.length) {
+      column.children.forEach(child => fillHeaders(child, depth + 1))
+
+      if (leafCount > 1) {
+        merges.push({
+          s: { r: depth, c: startColumnIndex },
+          e: { r: depth, c: startColumnIndex + leafCount - 1 }
+        })
+      }
+
+      return
+    }
+
+    leafColumns.push(column)
+    currentColumnIndex += 1
+
+    if (depth < maxDepth - 1) {
+      merges.push({
+        s: { r: depth, c: startColumnIndex },
+        e: { r: maxDepth - 1, c: startColumnIndex }
+      })
+    }
+  }
+
+  columns.forEach(column => fillHeaders(column, 0))
+
+  return {
+    headerRows,
+    leafColumns,
+    merges
+  }
+}
+
+function buildColumnWidths<Row>(
+  leafColumns: Array<ExcelExportColumn<Row>>,
+  dataRows: Array<Array<ExcelCellValue>>,
+  defaultColumnWidth: number,
+  autoWidth: boolean
+) {
+  return leafColumns.map((column, columnIndex) => {
+    const headerWidth = getDisplayLength(column.label)
+    const dataWidth = dataRows.reduce((maxWidth, row) => {
+      return Math.max(maxWidth, getDisplayLength(row[columnIndex]))
+    }, 0)
+
+    const targetWidth =
+      column.width ?? (autoWidth ? Math.max(defaultColumnWidth, headerWidth, dataWidth) : defaultColumnWidth)
+
+    return { wch: targetWidth }
+  })
+}
+
+function normalizeFileName(fileName: string) {
+  return fileName.endsWith('.xlsx') ? fileName : `${fileName}.xlsx`
+}
+
+export function exportExcel<Row = Record<string, any>>(options: ExcelExportOptions<Row>) {
+  const {
+    fileName,
+    sheetName = DEFAULT_SHEET_NAME,
+    data,
+    autoWidth = true,
+    defaultColumnWidth = DEFAULT_COLUMN_WIDTH
+  } = options
+  const columns = options.columns.filter(column => !!column)
+
+  if (!columns.length) {
+    throw new Error('Excel export columns can not be empty.')
+  }
+
+  const { headerRows, leafColumns, merges } = buildHeaderMatrix(columns)
+  const dataRows = data.map((row, rowIndex) => leafColumns.map(column => getCellValue(row, rowIndex, column)))
+
+  const worksheet = XLSX.utils.aoa_to_sheet([...headerRows, ...dataRows])
+  worksheet['!merges'] = merges
+  worksheet['!cols'] = buildColumnWidths(leafColumns, dataRows, defaultColumnWidth, autoWidth)
+
+  const workbook = XLSX.utils.book_new()
+  XLSX.utils.book_append_sheet(workbook, worksheet, sheetName)
+  XLSX.writeFile(workbook, normalizeFileName(fileName))
+}
+
+export default exportExcel

package/src/index.ts

@@ -0,0 +1,4 @@
+export { default as BaseExportButton } from './components/BaseExportButton'
+export * from './components/BaseExportButton'
+export { exportExcel } from './excel/exportExcel'
+export type { ExcelCellValue, ExcelExportColumn, ExcelExportOptions } from './excel/exportExcel'