@bsg-export/react 1.0.6 → 1.0.8

package/README.md

@@ -0,0 +1,123 @@
+# @bsg-export/react
+
+[![npm](https://img.shields.io/npm/v/@bsg-export/react)](https://www.npmjs.com/package/@bsg-export/react)
+
+> [belobog-stellar-grid](https://github.com/kurisu994/belobog-stellar-grid) 的 React 官方封装
+
+## 简介
+
+提供 `useExporter` Hook、`useWorkerExporter` Hook 和 `ExportButton` 组件，自动管理 WASM 初始化、导出状态和进度追踪。`useWorkerExporter` 支持将导出计算移至 Worker 线程。
+
+## 安装
+
+```bash
+npm install @bsg-export/react belobog-stellar-grid
+# 或
+pnpm add @bsg-export/react belobog-stellar-grid
+```
+
+**前置依赖**：`react >= 17.0.0`、`belobog-stellar-grid >= 1.0.0`
+
+## 快速开始
+
+### useExporter Hook
+
+```tsx
+import { useExporter, ExportFormat } from '@bsg-export/react';
+
+function App() {
+  const { initialized, loading, progress, error, exportTable, exportData } = useExporter();
+
+  return (
+    <button
+      disabled={!initialized || loading}
+      onClick={() =>
+        exportTable({
+          tableId: 'my-table',
+          filename: '报表.xlsx',
+          format: ExportFormat.Xlsx,
+        })
+      }
+    >
+      {loading ? `导出中 ${Math.round(progress)}%` : '导出 Excel'}
+    </button>
+  );
+}
+```
+
+### ExportButton 组件
+
+```tsx
+import { ExportButton, ExportFormat } from '@bsg-export/react';
+
+<ExportButton
+  tableId="my-table"
+  filename="报表.xlsx"
+  format={ExportFormat.Xlsx}
+  onExportSuccess={() => console.log('导出成功')}
+  onExportError={(err) => console.error('导出失败', err)}
+>
+  导出 Excel
+</ExportButton>
+```
+
+## API
+
+### `useExporter()` 返回值
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| `initialized` | `boolean` | WASM 是否初始化完成 |
+| `loading` | `boolean` | 是否正在导出 |
+| `progress` | `number` | 导出进度 (0-100) |
+| `error` | `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 工厂函数。
+
+```tsx
+import { useWorkerExporter } from '@bsg-export/react';
+import ExportWorkerScript from '@bsg-export/worker/worker?worker';
+
+const { initialized, loading, progress, exportData } = useWorkerExporter(
+  () => new ExportWorkerScript()
+);
+```
+
+| 属性/方法 | 类型 | 说明 |
+|-----------|------|------|
+| `initialized` | `boolean` | Worker 中 WASM 是否初始化完成 |
+| `loading` | `boolean` | 是否正在导出 |
+| `progress` | `number` | 导出进度 (0-100) |
+| `error` | `Error \| null` | 错误信息 |
+| `exportData` | `(data, opts?) => Promise<boolean>` | Worker 生成并下载 |
+| `generateBytes` | `(data, opts?) => Promise<Uint8Array>` | 仅生成字节 |
+| `terminate` | `() => void` | 销毁 Worker |
+
+### `<ExportButton>` Props
+
+继承所有 `<button>` HTML 属性，额外支持：
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `tableId` | `string` | — | 要导出的表格 ID（必填） |
+| `filename` | `string` | — | 导出文件名 |
+| `format` | `ExportFormat` | `Csv` | 导出格式 |
+| `excludeHidden` | `boolean` | `false` | 排除隐藏行/列 |
+| `withBom` | `boolean` | `false` | 添加 UTF-8 BOM |
+| `onExportSuccess` | `() => void` | — | 导出成功回调 |
+| `onExportError` | `(error) => void` | — | 导出失败回调 |
+| `onExportProgress` | `(progress) => void` | — | 进度变化回调 |
+| `initializingText` | `string` | `'初始化中...'` | 初始化中按钮文本 |
+| `loadingText` | `string` | `'导出中 {progress}%'` | 导出中按钮文本 |
+
+## 许可证
+
+MIT OR Apache-2.0

package/dist/ExportButton.js

@@ -34,18 +34,18 @@ export function ExportButton({ tableId, filename, format, excludeHidden, withBom
         buttonProps.onClick?.(e);
         if (e.defaultPrevented)
             return;
-        exportTable({
+        const success = exportTable({
             tableId,
             filename,
             format,
             excludeHidden,
             withBom,
         });
-        // 导出成功回调（同步导出完成后立即触发）
-        if (onExportSuccess && !error) {
+        // 导出成功回调（同步导出完成后检查返回值）
+        if (success && onExportSuccess) {
             onExportSuccess();
         }
-    }, [tableId, filename, format, excludeHidden, withBom, exportTable, onExportSuccess, error, buttonProps]);
+    }, [tableId, filename, format, excludeHidden, withBom, exportTable, onExportSuccess, buttonProps]);
     /** 渲染按钮文本 */
     const renderText = () => {
         if (!initialized)

package/dist/index.d.ts

@@ -6,9 +6,11 @@
  * @packageDocumentation
  */
 export { useExporter } from './use-exporter';
-export type { UseExporterReturn, ExportTableOptions, ExportTablesXlsxOptions, ExportCsvBatchOptions, ExportXlsxBatchOptions, ExportTablesBatchOptions, } from './use-exporter';
+export type { UseExporterReturn, } from './use-exporter';
+export { useWorkerExporter } from './use-worker-exporter';
+export type { UseWorkerExporterReturn, } from './use-worker-exporter';
 export { ExportButton } from './ExportButton';
 export type { ExportButtonProps } from './ExportButton';
-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,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,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,YAAY,EACV,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EACV,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,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

@@ -7,6 +7,7 @@
  */
 // Hook
 export { useExporter } from './use-exporter';
+export { useWorkerExporter } from './use-worker-exporter';
 // 组件
 export { ExportButton } from './ExportButton';
 export { ExportFormat } from '@bsg-export/types';

package/dist/use-exporter.d.ts

@@ -15,66 +15,7 @@
  * );
  * ```
  */
-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';
 /** useExporter Hook 的返回值 */
 export interface UseExporterReturn {
     /** WASM 是否已初始化完成 */
@@ -86,17 +27,17 @@ export interface UseExporterReturn {
     /** 错误信息 */
     error: Error | null;
     /** 导出 HTML 表格 */
-    exportTable: (options: ExportTableOptions) => void;
+    exportTable: (options: ExportTableOptions) => boolean;
     /** 从 JS 数组直接导出 */
-    exportData: (data: DataRow[], options?: ExportDataOptions) => void;
+    exportData: (data: DataRow[], options?: ExportDataOptions) => boolean;
     /** 多工作表同步导出 */
-    exportTablesXlsx: (options: ExportTablesXlsxOptions) => void;
+    exportTablesXlsx: (options: ExportTablesXlsxOptions) => boolean;
     /** 分批异步导出 CSV */
-    exportCsvBatch: (options: ExportCsvBatchOptions) => Promise<void>;
+    exportCsvBatch: (options: ExportCsvBatchOptions) => Promise<boolean>;
     /** 分批异步导出 XLSX */
-    exportXlsxBatch: (options: ExportXlsxBatchOptions) => Promise<void>;
+    exportXlsxBatch: (options: ExportXlsxBatchOptions) => Promise<boolean>;
     /** 多工作表分批异步导出 */
-    exportTablesBatch: (options: ExportTablesBatchOptions) => Promise<void>;
+    exportTablesBatch: (options: ExportTablesBatchOptions) => Promise<boolean>;
 }
 /**
  * WASM 导出管理 Hook

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;;;;;;;;;;;;;;;;GAgBG;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;AAED,4BAA4B;AAC5B,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,iBAAiB;IACjB,WAAW,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,IAAI,CAAC;IACnD,kBAAkB;IAClB,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnE,eAAe;IACf,gBAAgB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC7D,iBAAiB;IACjB,cAAc,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,kBAAkB;IAClB,eAAe,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,iBAAiB;IACjB,iBAAiB,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAuBD;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAwK/C"}
+{"version":3,"file":"use-exporter.d.ts","sourceRoot":"","sources":["../src/use-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EAExB,OAAO,EACR,MAAM,mBAAmB,CAAC;AAI3B,4BAA4B;AAC5B,MAAM,WAAW,iBAAiB;IAChC,oBAAoB;IACpB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,iBAAiB;IACjB,WAAW,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC;IACtD,kBAAkB;IAClB,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACtE,eAAe;IACf,gBAAgB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,OAAO,CAAC;IAChE,iBAAiB;IACjB,cAAc,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrE,kBAAkB;IAClB,eAAe,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvE,iBAAiB;IACjB,iBAAiB,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AA6BD;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAgL/C"}

package/dist/use-exporter.js

@@ -26,10 +26,16 @@ async function initWasm() {
     if (wasmModule)
         return wasmModule;
     if (!wasmInitPromise) {
-        wasmInitPromise = import('belobog-stellar-grid').then(async (mod) => {
+        wasmInitPromise = import('belobog-stellar-grid')
+            .then(async (mod) => {
             await mod.default();
             wasmModule = mod;
             return mod;
+        })
+            .catch((err) => {
+            // 初始化失败时重置 Promise，允许后续调用重试
+            wasmInitPromise = null;
+            throw err;
         });
     }
     return wasmInitPromise;
@@ -71,7 +77,7 @@ export function useExporter() {
     /** 包装同步导出操作 */
     const wrapSync = useCallback((fn) => {
         if (!initialized || !wasmModule)
-            return;
+            return false;
         setLoading(true);
         setProgress(0);
         setError(null);
@@ -79,10 +85,12 @@ export function useExporter() {
             fn();
             if (mountedRef.current)
                 setProgress(100);
+            return true;
         }
         catch (err) {
             if (mountedRef.current)
                 setError(err instanceof Error ? err : new Error(String(err)));
+            return false;
         }
         finally {
             if (mountedRef.current)
@@ -92,7 +100,7 @@ export function useExporter() {
     /** 包装异步导出操作 */
     const wrapAsync = useCallback(async (fn) => {
         if (!initialized || !wasmModule)
-            return;
+            return false;
         setLoading(true);
         setProgress(0);
         setError(null);
@@ -100,10 +108,12 @@ export function useExporter() {
             await fn();
             if (mountedRef.current)
                 setProgress(100);
+            return true;
         }
         catch (err) {
             if (mountedRef.current)
                 setError(err instanceof Error ? err : new Error(String(err)));
+            return false;
         }
         finally {
             if (mountedRef.current)
@@ -111,12 +121,12 @@ export function useExporter() {
         }
     }, [initialized]);
     const exportTable = useCallback((options) => {
-        wrapSync(() => {
+        return wrapSync(() => {
             wasmModule.export_table(options.tableId, options.filename, options.format, options.excludeHidden, createProgressCallback(), options.withBom, options.strictProgressCallback);
         });
     }, [wrapSync, createProgressCallback]);
     const exportData = useCallback((data, options) => {
-        wrapSync(() => {
+        return wrapSync(() => {
             const opts = options
                 ? { ...options, progressCallback: options.progressCallback ?? createProgressCallback() }
                 : { progressCallback: createProgressCallback() };
@@ -124,23 +134,23 @@ export function useExporter() {
         });
     }, [wrapSync, createProgressCallback]);
     const exportTablesXlsx = useCallback((options) => {
-        wrapSync(() => {
-            wasmModule.export_tables_xlsx(options.sheets, options.filename, createProgressCallback());
+        return wrapSync(() => {
+            wasmModule.export_tables_xlsx(options.sheets, options.filename, createProgressCallback(), options.strictProgressCallback);
         });
     }, [wrapSync, createProgressCallback]);
     const exportCsvBatch = useCallback(async (options) => {
-        await wrapAsync(async () => {
-            await wasmModule.export_table_to_csv_batch(options.tableId, options.tbodyId, options.filename, options.batchSize, options.excludeHidden, createProgressCallback(), options.withBom);
+        return await wrapAsync(async () => {
+            await wasmModule.export_table_to_csv_batch(options.tableId, options.tbodyId, options.filename, options.batchSize, options.excludeHidden, createProgressCallback(), options.withBom, options.strictProgressCallback);
         });
     }, [wrapAsync, createProgressCallback]);
     const exportXlsxBatch = useCallback(async (options) => {
-        await wrapAsync(async () => {
-            await wasmModule.export_table_to_xlsx_batch(options.tableId, options.tbodyId, options.filename, options.batchSize, options.excludeHidden, createProgressCallback());
+        return await wrapAsync(async () => {
+            await wasmModule.export_table_to_xlsx_batch(options.tableId, options.tbodyId, options.filename, options.batchSize, options.excludeHidden, createProgressCallback(), options.strictProgressCallback);
         });
     }, [wrapAsync, createProgressCallback]);
     const exportTablesBatch = useCallback(async (options) => {
-        await wrapAsync(async () => {
-            await wasmModule.export_tables_to_xlsx_batch(options.sheets, options.filename, options.batchSize, createProgressCallback());
+        return await wrapAsync(async () => {
+            await wasmModule.export_tables_to_xlsx_batch(options.sheets, options.filename, options.batchSize, createProgressCallback(), options.strictProgressCallback);
         });
     }, [wrapAsync, createProgressCallback]);
     return {

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

@@ -0,0 +1,46 @@
+/**
+ * useWorkerExporter - Worker 线程导出管理 Hook
+ *
+ * 将 CSV/XLSX 生成移至 Worker 线程，主线程不阻塞。
+ * 用户需要传入一个已创建的 Worker 实例。
+ *
+ * @example
+ * ```tsx
+ * // Vite
+ * import ExportWorkerScript from '@bsg-export/worker/worker?worker';
+ * const { initialized, loading, progress, exportData } = useWorkerExporter(() => new ExportWorkerScript());
+ *
+ * // Webpack 5
+ * const { exportData } = useWorkerExporter(
+ *   () => new Worker(new URL('@bsg-export/worker/worker', import.meta.url), { type: 'module' })
+ * );
+ * ```
+ */
+import type { ExportDataOptions, DataRow } from '@bsg-export/types';
+/** useWorkerExporter Hook 的返回值 */
+export interface UseWorkerExporterReturn {
+    /** Worker 中的 WASM 是否已初始化完成 */
+    initialized: boolean;
+    /** 是否正在导出 */
+    loading: boolean;
+    /** 导出进度 (0-100) */
+    progress: number;
+    /** 错误信息 */
+    error: 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;
+}
+/**
+ * Worker 线程导出管理 Hook
+ *
+ * 接收一个 Worker 工厂函数，自动管理 Worker 生命周期和 WASM 初始化。
+ * 导出计算在 Worker 线程执行，主线程保持响应。
+ *
+ * @param createWorker - 创建 Worker 实例的工厂函数
+ */
+export declare function useWorkerExporter(createWorker: () => Worker): UseWorkerExporterReturn;
+//# 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;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAEjB,OAAO,EACR,MAAM,mBAAmB,CAAC;AAE3B,kCAAkC;AAClC,MAAM,WAAW,uBAAuB;IACtC,8BAA8B;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,mBAAmB;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW;IACX,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0BAA0B;IAC1B,UAAU,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzG,8BAA8B;IAC9B,aAAa,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACtH,gBAAgB;IAChB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAiCD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,MAAM,GAAG,uBAAuB,CA6MrF"}

package/dist/use-worker-exporter.js

@@ -0,0 +1,225 @@
+/**
+ * useWorkerExporter - Worker 线程导出管理 Hook
+ *
+ * 将 CSV/XLSX 生成移至 Worker 线程，主线程不阻塞。
+ * 用户需要传入一个已创建的 Worker 实例。
+ *
+ * @example
+ * ```tsx
+ * // Vite
+ * import ExportWorkerScript from '@bsg-export/worker/worker?worker';
+ * const { initialized, loading, progress, exportData } = useWorkerExporter(() => new ExportWorkerScript());
+ *
+ * // Webpack 5
+ * const { exportData } = useWorkerExporter(
+ *   () => new Worker(new URL('@bsg-export/worker/worker', import.meta.url), { type: 'module' })
+ * );
+ * ```
+ */
+import { useState, useEffect, useCallback, useRef } from 'react';
+let requestCounter = 0;
+function generateId() {
+    return `req_${++requestCounter}_${Date.now()}`;
+}
+/**
+ * Worker 线程导出管理 Hook
+ *
+ * 接收一个 Worker 工厂函数，自动管理 Worker 生命周期和 WASM 初始化。
+ * 导出计算在 Worker 线程执行，主线程保持响应。
+ *
+ * @param createWorker - 创建 Worker 实例的工厂函数
+ */
+export function useWorkerExporter(createWorker) {
+    const [initialized, setInitialized] = useState(false);
+    const [loading, setLoading] = useState(false);
+    const [progress, setProgress] = useState(0);
+    const [error, setError] = useState(null);
+    const workerRef = useRef(null);
+    const pendingRef = useRef(new Map());
+    const mountedRef = useRef(true);
+    // 处理 Worker 消息
+    const handleMessage = useCallback((event) => {
+        if (!mountedRef.current)
+            return;
+        const { type, id, bytes, message, progress: prog } = event.data;
+        const pending = pendingRef.current.get(id);
+        if (!pending)
+            return;
+        switch (type) {
+            case 'ready':
+                pendingRef.current.delete(id);
+                pending.resolve(new ArrayBuffer(0));
+                break;
+            case 'result':
+                pendingRef.current.delete(id);
+                pending.resolve(bytes);
+                break;
+            case 'error':
+                pendingRef.current.delete(id);
+                pending.reject(new Error(message ?? '未知错误'));
+                break;
+            case 'progress':
+                if (pending.onProgress && prog !== undefined) {
+                    pending.onProgress(prog);
+                }
+                break;
+        }
+    }, []);
+    // 处理 Worker 错误
+    const handleError = useCallback((event) => {
+        if (!mountedRef.current)
+            return;
+        const err = new Error(`Worker 错误: ${event.message}`);
+        for (const [id, pending] of pendingRef.current) {
+            pending.reject(err);
+            pendingRef.current.delete(id);
+        }
+        setError(err);
+    }, []);
+    // 初始化 Worker 和 WASM
+    useEffect(() => {
+        mountedRef.current = true;
+        const worker = createWorker();
+        workerRef.current = worker;
+        worker.addEventListener('message', handleMessage);
+        worker.addEventListener('error', handleError);
+        // 发送 init 消息
+        const id = generateId();
+        const initPromise = new Promise((resolve, reject) => {
+            pendingRef.current.set(id, { resolve, reject });
+        });
+        const request = { type: 'init', id };
+        worker.postMessage(request);
+        initPromise
+            .then(() => {
+            if (mountedRef.current)
+                setInitialized(true);
+        })
+            .catch((err) => {
+            if (mountedRef.current)
+                setError(err instanceof Error ? err : new Error(String(err)));
+        });
+        return () => {
+            mountedRef.current = false;
+            // 拒绝所有待处理请求
+            for (const [, pending] of pendingRef.current) {
+                pending.reject(new Error('组件已卸载'));
+            }
+            pendingRef.current.clear();
+            worker.terminate();
+            workerRef.current = null;
+        };
+    }, []); // eslint-disable-line react-hooks/exhaustive-deps
+    /** 向 Worker 发送生成请求 */
+    const sendGenerate = useCallback((data, options) => {
+        const worker = workerRef.current;
+        if (!worker)
+            return Promise.reject(new Error('Worker 未创建'));
+        return new Promise((resolve, reject) => {
+            const id = generateId();
+            pendingRef.current.set(id, {
+                resolve,
+                reject,
+                onProgress: (p) => {
+                    if (mountedRef.current)
+                        setProgress(p);
+                },
+            });
+            const request = {
+                type: 'generate',
+                id,
+                data,
+                options: (options ?? {}),
+            };
+            worker.postMessage(request);
+        });
+    }, []);
+    /** 在主线程触发文件下载 */
+    const downloadFile = useCallback((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), 10_000);
+    }, []);
+    /** 在 Worker 中生成文件并触发下载 */
+    const exportData = useCallback(async (data, options) => {
+        if (!initialized)
+            return false;
+        setLoading(true);
+        setProgress(0);
+        setError(null);
+        try {
+            const buffer = await sendGenerate(data, options);
+            const bytes = new Uint8Array(buffer);
+            downloadFile(bytes, options?.filename, options?.format);
+            if (mountedRef.current)
+                setProgress(100);
+            return true;
+        }
+        catch (err) {
+            if (mountedRef.current)
+                setError(err instanceof Error ? err : new Error(String(err)));
+            return false;
+        }
+        finally {
+            if (mountedRef.current)
+                setLoading(false);
+        }
+    }, [initialized, sendGenerate, downloadFile]);
+    /** 在 Worker 中生成文件字节（不触发下载） */
+    const generateBytes = useCallback(async (data, options) => {
+        if (!initialized)
+            return null;
+        setLoading(true);
+        setProgress(0);
+        setError(null);
+        try {
+            const buffer = await sendGenerate(data, options);
+            if (mountedRef.current)
+                setProgress(100);
+            return new Uint8Array(buffer);
+        }
+        catch (err) {
+            if (mountedRef.current)
+                setError(err instanceof Error ? err : new Error(String(err)));
+            return null;
+        }
+        finally {
+            if (mountedRef.current)
+                setLoading(false);
+        }
+    }, [initialized, sendGenerate]);
+    /** 手动销毁 Worker */
+    const terminate = useCallback(() => {
+        for (const [, pending] of pendingRef.current) {
+            pending.reject(new Error('Worker 已被手动销毁'));
+        }
+        pendingRef.current.clear();
+        workerRef.current?.terminate();
+        workerRef.current = null;
+        if (mountedRef.current) {
+            setInitialized(false);
+        }
+    }, []);
+    return {
+        initialized,
+        loading,
+        progress,
+        error,
+        exportData,
+        generateBytes,
+        terminate,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsg-export/react",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "belobog-stellar-grid 的 React 官方封装组件",
   "type": "module",
   "main": "./dist/index.js",
@@ -40,8 +40,8 @@
     "@bsg-export/types": "file:../types"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
-    "react": "^19.0.0",
-    "typescript": "^5.7.0"
+    "@types/react": "^19.2.14",
+    "react": "^19.2.4",
+    "typescript": "^5.9.3"
   }
 }