@bsg-export/vue 1.0.6 → 1.0.8

package/README.md

@@ -0,0 +1,135 @@
+# @bsg-export/vue
+
+[![npm](https://img.shields.io/npm/v/@bsg-export/vue)](https://www.npmjs.com/package/@bsg-export/vue)
+
+> [belobog-stellar-grid](https://github.com/kurisu994/belobog-stellar-grid) 的 Vue 3 官方封装
+
+## 简介
+
+提供 `useExporter` Composable、`useWorkerExporter` Composable 和 `ExportButton` 组件，自动管理 WASM 初始化、导出状态和进度追踪。`useWorkerExporter` 支持将导出计算移至 Worker 线程。
+
+## 安装
+
+```bash
+npm install @bsg-export/vue belobog-stellar-grid
+# 或
+pnpm add @bsg-export/vue belobog-stellar-grid
+```
+
+**前置依赖**：`vue >= 3.3.0`、`belobog-stellar-grid >= 1.0.0`
+
+## 快速开始
+
+### useExporter Composable
+
+```vue
+<script setup lang="ts">
+import { useExporter, ExportFormat } from '@bsg-export/vue';
+
+const { initialized, loading, progress, exportTable } = useExporter();
+</script>
+
+<template>
+  <button
+    :disabled="!initialized || loading"
+    @click="exportTable({ tableId: 'my-table', filename: '报表.xlsx', format: ExportFormat.Xlsx })"
+  >
+    {{ loading ? `导出中 ${Math.round(progress)}%` : '导出 Excel' }}
+  </button>
+</template>
+```
+
+### ExportButton 组件
+
+```vue
+<script setup lang="ts">
+import { ExportButton, ExportFormat } from '@bsg-export/vue';
+</script>
+
+<template>
+  <ExportButton
+    table-id="my-table"
+    filename="报表.xlsx"
+    :format="ExportFormat.Xlsx"
+    @success="console.log('导出成功')"
+    @error="(err) => console.error('导出失败', err)"
+  >
+    导出 Excel
+  </ExportButton>
+</template>
+```
+
+## API
+
+### `useExporter()` 返回值
+
+所有返回值均为 Vue 3 响应式 `Ref`。
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| `initialized` | `Ref<boolean>` | WASM 是否初始化完成 |
+| `loading` | `Ref<boolean>` | 是否正在导出 |
+| `progress` | `Ref<number>` | 导出进度 (0-100) |
+| `error` | `Ref<Error \| null>` | 错误信息 |
+| `exportTable` | `(options) => void` | DOM 表格导出 |
+| `exportData` | `(data, options?) => void` | 纯数据导出 |
+| `exportTablesXlsx` | `(options) => void` | 多 Sheet 导出 |
+| `exportCsvBatch` | `(options) => Promise` | CSV 分批导出 |
+| `exportXlsxBatch` | `(options) => Promise` | XLSX 分批导出 |
+| `exportTablesBatch` | `(options) => Promise` | 多 Sheet 分批导出 |
+
+### `useWorkerExporter(createWorker)` 返回值
+
+将导出计算移至 Worker 线程，主线程不阻塞。需要传入 Worker 工厂函数。
+
+```vue
+<script setup lang="ts">
+import { useWorkerExporter } from '@bsg-export/vue';
+import ExportWorkerScript from '@bsg-export/worker/worker?worker';
+
+const { initialized, loading, progress, exportData } = useWorkerExporter(
+  () => new ExportWorkerScript()
+);
+</script>
+```
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| `initialized` | `Ref<boolean>` | Worker 中 WASM 是否初始化完成 |
+| `loading` | `Ref<boolean>` | 是否正在导出 |
+| `progress` | `Ref<number>` | 导出进度 (0-100) |
+| `error` | `Ref<Error \| null>` | 错误信息 |
+| `exportData` | `(data, opts?) => Promise<boolean>` | Worker 生成并下载 |
+| `generateBytes` | `(data, opts?) => Promise<Uint8Array>` | 仅生成字节 |
+| `terminate` | `() => void` | 销毁 Worker |
+
+### `<ExportButton>` Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `table-id` | `string` | — | 要导出的表格 ID（必填） |
+| `filename` | `string` | — | 导出文件名 |
+| `format` | `ExportFormat` | `Csv` | 导出格式 |
+| `exclude-hidden` | `boolean` | `false` | 排除隐藏行/列 |
+| `with-bom` | `boolean` | `false` | 添加 UTF-8 BOM |
+| `disabled` | `boolean` | `false` | 是否禁用按钮 |
+| `initializing-text` | `string` | `'初始化中...'` | 初始化中按钮文本 |
+| `loading-text` | `string` | `'导出中 {progress}%'` | 导出中按钮文本 |
+
+### 事件
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `success` | — | 导出成功 |
+| `error` | `Error` | 导出失败 |
+| `progress` | `number` | 进度变化 |
+
+### 插槽
+
+| 插槽 | 说明 |
+|------|------|
+| `default` | 按钮内容（默认显示"导出"） |
+
+## 许可证
+
+MIT OR Apache-2.0

package/dist/ExportButton.vue.d.ts

@@ -33,13 +33,13 @@ type __VLS_Slots = {} & {
     default?: (props: typeof __VLS_1) => any;
 };
 declare const __VLS_component: import("vue").DefineComponent<ExportButtonProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
-    success: () => any;
     error: (error: Error) => any;
     progress: (progress: number) => any;
+    success: () => any;
 }, string, import("vue").PublicProps, Readonly<ExportButtonProps> & Readonly<{
-    onSuccess?: (() => any) | undefined;
     onError?: ((error: Error) => any) | undefined;
     onProgress?: ((progress: number) => any) | undefined;
+    onSuccess?: (() => any) | undefined;
 }>, {
     disabled: boolean;
     initializingText: string;

package/dist/ExportButton.vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExportButton.vue.d.ts","sourceRoot":"","sources":["../src/ExportButton.vue"],"names":[],"mappings":"AA4FA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD,eAAe;AACf,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,gBAAgB;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA4ED,QAAA,IAAI,OAAO,IAAW,CAAE;AACxB,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,CAAC;AAwB/C,QAAA,MAAM,eAAe;;;;;;;;;cA3GR,OAAO;sBAEC,MAAM;iBAEX,MAAM;6EA+GpB,CAAC;wBACkB,eAAe,CAAC,OAAO,eAAe,EAAE,WAAW,CAAC;AAAzE,wBAA0E;AAa1E,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KAEV,CAAA;CACD,CAAC"}
+{"version":3,"file":"ExportButton.vue.d.ts","sourceRoot":"","sources":["../src/ExportButton.vue"],"names":[],"mappings":"AAiGA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAItD,eAAe;AACf,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,gBAAgB;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAiFD,QAAA,IAAI,OAAO,IAAW,CAAE;AACxB,KAAK,WAAW,GAAG,EAAE,GACnB;IAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,OAAO,KAAK,GAAG,CAAA;CAAE,CAAC;AAwB/C,QAAA,MAAM,eAAe;;;;;;;;;cAhHR,OAAO;sBAEC,MAAM;iBAEX,MAAM;6EAoHpB,CAAC;wBACkB,eAAe,CAAC,OAAO,eAAe,EAAE,WAAW,CAAC;AAAzE,wBAA0E;AAa1E,KAAK,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG;IAChC,QAAO;QACN,MAAM,EAAE,CAAC,CAAC;KAEV,CAAA;CACD,CAAC"}

package/dist/index.d.ts

@@ -6,8 +6,8 @@
  * @packageDocumentation
  */
 export { useExporter } from './use-exporter';
-export type { ExportTableOptions, ExportTablesXlsxOptions, ExportCsvBatchOptions, ExportXlsxBatchOptions, ExportTablesBatchOptions, } from './use-exporter';
+export { useWorkerExporter } from './use-worker-exporter';
 export { default as ExportButton } from './ExportButton.vue';
-export type { Column, MergeCellValue, CellValue, MergeableCellValue, DataRow, ExportDataOptions, SheetConfig, BatchSheetConfig, ProgressCallback, } from '@bsg-export/types';
+export type { Column, MergeCellValue, CellValue, MergeableCellValue, DataRow, ExportDataOptions, SheetConfig, BatchSheetConfig, ProgressCallback, ExportTableOptions, ExportTablesXlsxOptions, ExportCsvBatchOptions, ExportXlsxBatchOptions, ExportTablesBatchOptions, } from '@bsg-export/types';
 export { ExportFormat } from '@bsg-export/types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EACV,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG7D,YAAY,EACV,MAAM,EACN,cAAc,EACd,SAAS,EACT,kBAAkB,EAClB,OAAO,EACP,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG7D,YAAY,EACV,MAAM,EACN,cAAc,EACd,SAAS,EACT,kBAAkB,EAClB,OAAO,EACP,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,8 +1,10 @@
 import { useExporter } from "./use-exporter";
+import { useWorkerExporter } from "./use-worker-exporter";
 import { default as default2 } from "./ExportButton.vue";
 import { ExportFormat } from "@bsg-export/types";
 export {
   default2 as ExportButton,
   ExportFormat,
-  useExporter
+  useExporter,
+  useWorkerExporter
 };

package/dist/use-exporter.d.ts

@@ -19,66 +19,7 @@
  * </template>
  * ```
  */
-import type { ExportFormat, ExportDataOptions, SheetConfig, BatchSheetConfig, DataRow } from '@bsg-export/types';
-/** export_table 的参数配置 */
-export interface ExportTableOptions {
-    /** 要导出的 HTML 表格元素的 ID */
-    tableId: string;
-    /** 导出文件名 */
-    filename?: string;
-    /** 导出格式 */
-    format?: ExportFormat;
-    /** 是否排除隐藏行/列 */
-    excludeHidden?: boolean;
-    /** 是否添加 UTF-8 BOM（仅 CSV 有效） */
-    withBom?: boolean;
-    /** 回调失败是否中断导出 */
-    strictProgressCallback?: boolean;
-}
-/** 多工作表导出的参数配置 */
-export interface ExportTablesXlsxOptions {
-    /** Sheet 配置数组 */
-    sheets: SheetConfig[];
-    /** 导出文件名 */
-    filename?: string;
-}
-/** 分批导出 CSV 的参数配置 */
-export interface ExportCsvBatchOptions {
-    /** 要导出的 HTML 表格元素的 ID */
-    tableId: string;
-    /** 可选的独立 tbody ID */
-    tbodyId?: string;
-    /** 导出文件名 */
-    filename?: string;
-    /** 每批处理行数 */
-    batchSize?: number;
-    /** 是否排除隐藏行/列 */
-    excludeHidden?: boolean;
-    /** 是否添加 UTF-8 BOM */
-    withBom?: boolean;
-}
-/** 分批导出 XLSX 的参数配置 */
-export interface ExportXlsxBatchOptions {
-    /** 要导出的 HTML 表格元素的 ID */
-    tableId: string;
-    /** 可选的独立 tbody ID */
-    tbodyId?: string;
-    /** 导出文件名 */
-    filename?: string;
-    /** 每批处理行数 */
-    batchSize?: number;
-    /** 是否排除隐藏行/列 */
-    excludeHidden?: boolean;
-}
-/** 多工作表分批导出的参数配置 */
-export interface ExportTablesBatchOptions {
-    /** Sheet 配置数组 */
-    sheets: BatchSheetConfig[];
-    /** 导出文件名 */
-    filename?: string;
-    /** 每批处理行数 */
-    batchSize?: number;
-}
+import type { ExportDataOptions, ExportTableOptions, ExportTablesXlsxOptions, ExportCsvBatchOptions, ExportXlsxBatchOptions, ExportTablesBatchOptions, DataRow } from '@bsg-export/types';
 /**
  * WASM 导出管理 Composable
  *
@@ -94,11 +35,11 @@ export declare function useExporter(): {
     progress: import("vue").Ref<number, number>;
     /** 错误信息 */
     error: import("vue").Ref<Error | null, Error | null>;
-    exportTable: (options: ExportTableOptions) => void;
-    exportData: (data: DataRow[], options?: ExportDataOptions) => void;
-    exportTablesXlsx: (options: ExportTablesXlsxOptions) => void;
-    exportCsvBatch: (options: ExportCsvBatchOptions) => Promise<void>;
-    exportXlsxBatch: (options: ExportXlsxBatchOptions) => Promise<void>;
-    exportTablesBatch: (options: ExportTablesBatchOptions) => Promise<void>;
+    exportTable: (options: ExportTableOptions) => boolean;
+    exportData: (data: DataRow[], options?: ExportDataOptions) => boolean;
+    exportTablesXlsx: (options: ExportTablesXlsxOptions) => boolean;
+    exportCsvBatch: (options: ExportCsvBatchOptions) => Promise<boolean>;
+    exportXlsxBatch: (options: ExportXlsxBatchOptions) => Promise<boolean>;
+    exportTablesBatch: (options: ExportTablesBatchOptions) => Promise<boolean>;
 };
 //# sourceMappingURL=use-exporter.d.ts.map

package/dist/use-exporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-exporter.d.ts","sourceRoot":"","sources":["../src/use-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAEhB,OAAO,EACR,MAAM,mBAAmB,CAAC;AAE3B,yBAAyB;AACzB,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,gBAAgB;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB;IACjB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,kBAAkB;AAClB,MAAM,WAAW,uBAAuB;IACtC,iBAAiB;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAqB;AACrB,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qBAAqB;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,sBAAsB;AACtB,MAAM,WAAW,sBAAsB;IACrC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,oBAAoB;AACpB,MAAM,WAAW,wBAAwB;IACvC,iBAAiB;IACjB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuBD;;;;;GAKG;AACH,wBAAgB,WAAW;IA2IvB,oBAAoB;;IAEpB,aAAa;;IAEb,mBAAmB;;IAEnB,WAAW;;2BAnFiB,kBAAkB;uBAetB,OAAO,EAAE,YAAY,iBAAiB;gCAU7B,uBAAuB;8BAWnB,qBAAqB;+BAepB,sBAAsB;iCAcpB,wBAAwB;EA2BnE"}
+{"version":3,"file":"use-exporter.d.ts","sourceRoot":"","sources":["../src/use-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EAExB,OAAO,EACR,MAAM,mBAAmB,CAAC;AA+B3B;;;;;GAKG;AACH,wBAAgB,WAAW;IAmJvB,oBAAoB;;IAEpB,aAAa;;IAEb,mBAAmB;;IAEnB,WAAW;;2BAvFiB,kBAAkB;uBAetB,OAAO,EAAE,YAAY,iBAAiB;gCAU7B,uBAAuB;8BAYnB,qBAAqB;+BAgBpB,sBAAsB;iCAepB,wBAAwB;EA4BnE"}

package/dist/use-exporter.js

@@ -8,6 +8,9 @@ async function initWasm() {
       await mod.default();
       wasmModule = mod;
       return mod;
+    }).catch((err) => {
+      wasmInitPromise = null;
+      throw err;
     });
   }
   return wasmInitPromise;
@@ -35,35 +38,39 @@ function useExporter() {
     };
   };
   const wrapSync = (fn) => {
-    if (!initialized.value || !wasmModule) return;
+    if (!initialized.value || !wasmModule) return false;
     loading.value = true;
     progress.value = 0;
     error.value = null;
     try {
       fn();
       if (mounted) progress.value = 100;
+      return true;
     } catch (err) {
       if (mounted) error.value = err instanceof Error ? err : new Error(String(err));
+      return false;
     } finally {
       if (mounted) loading.value = false;
     }
   };
   const wrapAsync = async (fn) => {
-    if (!initialized.value || !wasmModule) return;
+    if (!initialized.value || !wasmModule) return false;
     loading.value = true;
     progress.value = 0;
     error.value = null;
     try {
       await fn();
       if (mounted) progress.value = 100;
+      return true;
     } catch (err) {
       if (mounted) error.value = err instanceof Error ? err : new Error(String(err));
+      return false;
     } finally {
       if (mounted) loading.value = false;
     }
   };
   const exportTable = (options) => {
-    wrapSync(() => {
+    return wrapSync(() => {
       wasmModule.export_table(
         options.tableId,
         options.filename,
@@ -76,22 +83,23 @@ function useExporter() {
     });
   };
   const exportData = (data, options) => {
-    wrapSync(() => {
+    return wrapSync(() => {
       const opts = options ? { ...options, progressCallback: options.progressCallback ?? createProgressCallback() } : { progressCallback: createProgressCallback() };
       wasmModule.export_data(data, opts);
     });
   };
   const exportTablesXlsx = (options) => {
-    wrapSync(() => {
+    return wrapSync(() => {
       wasmModule.export_tables_xlsx(
         options.sheets,
         options.filename,
-        createProgressCallback()
+        createProgressCallback(),
+        options.strictProgressCallback
       );
     });
   };
   const exportCsvBatch = async (options) => {
-    await wrapAsync(async () => {
+    return await wrapAsync(async () => {
       await wasmModule.export_table_to_csv_batch(
         options.tableId,
         options.tbodyId,
@@ -99,29 +107,32 @@ function useExporter() {
         options.batchSize,
         options.excludeHidden,
         createProgressCallback(),
-        options.withBom
+        options.withBom,
+        options.strictProgressCallback
       );
     });
   };
   const exportXlsxBatch = async (options) => {
-    await wrapAsync(async () => {
+    return await wrapAsync(async () => {
       await wasmModule.export_table_to_xlsx_batch(
         options.tableId,
         options.tbodyId,
         options.filename,
         options.batchSize,
         options.excludeHidden,
-        createProgressCallback()
+        createProgressCallback(),
+        options.strictProgressCallback
       );
     });
   };
   const exportTablesBatch = async (options) => {
-    await wrapAsync(async () => {
+    return await wrapAsync(async () => {
       await wasmModule.export_tables_to_xlsx_batch(
         options.sheets,
         options.filename,
         options.batchSize,
-        createProgressCallback()
+        createProgressCallback(),
+        options.strictProgressCallback
       );
     });
   };

package/dist/use-worker-exporter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * useWorkerExporter - Worker 线程导出管理 Composable
+ *
+ * 将 CSV/XLSX 生成移至 Worker 线程，主线程不阻塞。
+ * 用户需要传入一个已创建的 Worker 实例。
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { useWorkerExporter } from '@bsg-export/vue';
+ *
+ * // Vite
+ * import ExportWorkerScript from '@bsg-export/worker/worker?worker';
+ * const { initialized, loading, progress, exportData } = useWorkerExporter(() => new ExportWorkerScript());
+ * </script>
+ *
+ * <template>
+ *   <button :disabled="!initialized || loading" @click="exportData(data, { columns, filename: '报表.xlsx', format: 1 })">
+ *     {{ loading ? `导出中 ${Math.round(progress)}%` : '导出' }}
+ *   </button>
+ * </template>
+ * ```
+ */
+import type { ExportDataOptions, DataRow } from '@bsg-export/types';
+/**
+ * Worker 线程导出管理 Composable
+ *
+ * 接收一个 Worker 工厂函数，自动管理 Worker 生命周期和 WASM 初始化。
+ * 导出计算在 Worker 线程执行，主线程保持响应。
+ *
+ * @param createWorker - 创建 Worker 实例的工厂函数
+ */
+export declare function useWorkerExporter(createWorker: () => Worker): {
+    /** Worker 中的 WASM 是否已初始化完成 */
+    initialized: import("vue").Ref<boolean, boolean>;
+    /** 是否正在导出 */
+    loading: import("vue").Ref<boolean, boolean>;
+    /** 导出进度 (0-100) */
+    progress: import("vue").Ref<number, number>;
+    /** 错误信息 */
+    error: import("vue").Ref<Error | null, Error | null>;
+    /** 在 Worker 中生成文件并触发下载 */
+    exportData: (data: DataRow[], options?: Omit<ExportDataOptions, "progressCallback">) => Promise<boolean>;
+    /** 在 Worker 中生成文件字节（不触发下载） */
+    generateBytes: (data: DataRow[], options?: Omit<ExportDataOptions, "progressCallback">) => Promise<Uint8Array | null>;
+    /** 销毁 Worker */
+    terminate: () => void;
+};
+//# sourceMappingURL=use-worker-exporter.d.ts.map

package/dist/use-worker-exporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-worker-exporter.d.ts","sourceRoot":"","sources":["../src/use-worker-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAEjB,OAAO,EACR,MAAM,mBAAmB,CAAC;AAiC3B;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,MAAM;IAiMxD,8BAA8B;;IAE9B,aAAa;;IAEb,mBAAmB;;IAEnB,WAAW;;IAEX,0BAA0B;uBA9DpB,OAAO,EAAE,YACL,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,KACpD,OAAO,CAAC,OAAO,CAAC;IA8DjB,8BAA8B;0BAzCxB,OAAO,EAAE,YACL,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,KACpD,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAyC3B,gBAAgB;;EAGnB"}

package/dist/use-worker-exporter.js

@@ -0,0 +1,172 @@
+import { ref, onMounted, onUnmounted } from "vue";
+let requestCounter = 0;
+function generateId() {
+  return `req_${++requestCounter}_${Date.now()}`;
+}
+function useWorkerExporter(createWorker) {
+  const initialized = ref(false);
+  const loading = ref(false);
+  const progress = ref(0);
+  const error = ref(null);
+  let worker = null;
+  const pending = /* @__PURE__ */ new Map();
+  let mounted = true;
+  const handleMessage = (event) => {
+    if (!mounted) return;
+    const { type, id, bytes, message, progress: prog } = event.data;
+    const req = pending.get(id);
+    if (!req) return;
+    switch (type) {
+      case "ready":
+        pending.delete(id);
+        req.resolve(new ArrayBuffer(0));
+        break;
+      case "result":
+        pending.delete(id);
+        req.resolve(bytes);
+        break;
+      case "error":
+        pending.delete(id);
+        req.reject(new Error(message ?? "\u672A\u77E5\u9519\u8BEF"));
+        break;
+      case "progress":
+        if (req.onProgress && prog !== void 0) {
+          req.onProgress(prog);
+        }
+        break;
+    }
+  };
+  const handleError = (event) => {
+    if (!mounted) return;
+    const err = new Error(`Worker \u9519\u8BEF: ${event.message}`);
+    for (const [id, req] of pending) {
+      req.reject(err);
+      pending.delete(id);
+    }
+    error.value = err;
+  };
+  onMounted(() => {
+    mounted = true;
+    worker = createWorker();
+    worker.addEventListener("message", handleMessage);
+    worker.addEventListener("error", handleError);
+    const id = generateId();
+    const initPromise = new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject });
+    });
+    const request = { type: "init", id };
+    worker.postMessage(request);
+    initPromise.then(() => {
+      if (mounted) initialized.value = true;
+    }).catch((err) => {
+      if (mounted) error.value = err instanceof Error ? err : new Error(String(err));
+    });
+  });
+  onUnmounted(() => {
+    mounted = false;
+    for (const [, req] of pending) {
+      req.reject(new Error("\u7EC4\u4EF6\u5DF2\u5378\u8F7D"));
+    }
+    pending.clear();
+    worker?.terminate();
+    worker = null;
+  });
+  const sendGenerate = (data, options) => {
+    if (!worker) return Promise.reject(new Error("Worker \u672A\u521B\u5EFA"));
+    return new Promise((resolve, reject) => {
+      const id = generateId();
+      pending.set(id, {
+        resolve,
+        reject,
+        onProgress: (p) => {
+          if (mounted) progress.value = p;
+        }
+      });
+      const request = {
+        type: "generate",
+        id,
+        data,
+        options: options ?? {}
+      };
+      worker.postMessage(request);
+    });
+  };
+  const downloadFile = (bytes, filename, format) => {
+    const isXlsx = format === 1;
+    const mimeType = isXlsx ? "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" : "text/csv;charset=utf-8";
+    const defaultExt = isXlsx ? "xlsx" : "csv";
+    let finalFilename = filename ?? `export.${defaultExt}`;
+    if (!finalFilename.endsWith(`.${defaultExt}`)) {
+      finalFilename = `${finalFilename}.${defaultExt}`;
+    }
+    const blob = new Blob([bytes.buffer], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = finalFilename;
+    anchor.click();
+    setTimeout(() => URL.revokeObjectURL(url), 1e4);
+  };
+  const exportData = async (data, options) => {
+    if (!initialized.value) return false;
+    loading.value = true;
+    progress.value = 0;
+    error.value = null;
+    try {
+      const buffer = await sendGenerate(data, options);
+      const bytes = new Uint8Array(buffer);
+      downloadFile(bytes, options?.filename, options?.format);
+      if (mounted) progress.value = 100;
+      return true;
+    } catch (err) {
+      if (mounted) error.value = err instanceof Error ? err : new Error(String(err));
+      return false;
+    } finally {
+      if (mounted) loading.value = false;
+    }
+  };
+  const generateBytes = async (data, options) => {
+    if (!initialized.value) return null;
+    loading.value = true;
+    progress.value = 0;
+    error.value = null;
+    try {
+      const buffer = await sendGenerate(data, options);
+      if (mounted) progress.value = 100;
+      return new Uint8Array(buffer);
+    } catch (err) {
+      if (mounted) error.value = err instanceof Error ? err : new Error(String(err));
+      return null;
+    } finally {
+      if (mounted) loading.value = false;
+    }
+  };
+  const terminate = () => {
+    for (const [, req] of pending) {
+      req.reject(new Error("Worker \u5DF2\u88AB\u624B\u52A8\u9500\u6BC1"));
+    }
+    pending.clear();
+    worker?.terminate();
+    worker = null;
+    if (mounted) initialized.value = false;
+  };
+  return {
+    /** Worker 中的 WASM 是否已初始化完成 */
+    initialized,
+    /** 是否正在导出 */
+    loading,
+    /** 导出进度 (0-100) */
+    progress,
+    /** 错误信息 */
+    error,
+    /** 在 Worker 中生成文件并触发下载 */
+    exportData,
+    /** 在 Worker 中生成文件字节（不触发下载） */
+    generateBytes,
+    /** 销毁 Worker */
+    terminate
+  };
+}
+export {
+  useWorkerExporter
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsg-export/vue",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "belobog-stellar-grid 的 Vue 3 官方封装组件",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "vue-tsc --declaration --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/use-exporter.ts --outdir=dist --format=esm --bundle=false",
+    "build": "vue-tsc --declaration --emitDeclarationOnly --outDir dist && esbuild src/index.ts src/use-exporter.ts src/use-worker-exporter.ts --outdir=dist --format=esm --bundle=false",
     "typecheck": "vue-tsc --noEmit"
   },
   "keywords": [
@@ -40,9 +40,9 @@
     "@bsg-export/types": "file:../types"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
-    "typescript": "^5.7.0",
-    "vue": "^3.5.0",
-    "vue-tsc": "^2.2.0"
+    "esbuild": "^0.25.12",
+    "typescript": "^5.9.3",
+    "vue": "^3.5.29",
+    "vue-tsc": "^2.2.12"
   }
 }