@bsg-export/react 1.0.7 → 1.0.9

package/README.md

@@ -6,7 +6,7 @@
 
 ## 简介
 
-提供 `useExporter` Hook 和 `ExportButton` 组件，自动管理 WASM 初始化、导出状态和进度追踪。
+提供 `useExporter` Hook、`useWorkerExporter` Hook 和 `ExportButton` 组件，自动管理 WASM 初始化、导出状态和进度追踪。`useWorkerExporter` 支持将导出计算移至 Worker 线程。
 
 ## 安装
 
@@ -78,6 +78,29 @@ import { ExportButton, ExportFormat } from '@bsg-export/react';
 | `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 属性，额外支持：

package/dist/index.d.ts

@@ -7,6 +7,8 @@
  */
 export { useExporter } 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, ExportTableOptions, ExportTablesXlsxOptions, ExportCsvBatchOptions, ExportXlsxBatchOptions, ExportTablesBatchOptions, } from '@bsg-export/types';

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,GAClB,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,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,GACzB,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.map

@@ -1 +1 @@
-{"version":3,"file":"use-exporter.d.ts","sourceRoot":"","sources":["../src/use-exporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAEV,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"}
+{"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-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.7",
+  "version": "1.0.9",
   "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"
   }
 }