@ticatec/batch-data-uploader 0.0.4 → 0.0.10

package/README.md

@@ -1,154 +1,107 @@
-# Excel Batch Data Upload Component
+# Excel Data Batch Upload Processing Component / Data Recognition Component
 
-[[中文文档](./README_CN.md)]
+## [中文文档](./README_CN.md)
 
-This component is designed to batch import data from Excel files and handle uploads. It supports upload status management, exporting error rows, multilingual adaptation, data preprocessing, and more. By defining template classes and using a unified UI dialog component, it enables quick adaptation for various types of Excel data upload needs.
+# @ticatec/batch-data-uploader
 
-## Features
-
-* Parse `.xls` / `.xlsx` files
-* Custom column mapping and formatting
-* Batch upload with configurable batch size
-* Extensible data preprocessing logic (e.g., merging, grouping)
-* Upload status display: Pending, Uploading, Success, Failed
-* Export error rows to Excel
-* Multilingual support (based on `@ticatec/i18n`)
+A universal Svelte component for batch data uploading, supporting Excel file parsing, local preprocessing, field mapping validation, multilingual prompts, import validation, and error messaging.
 
 ---
 
-## Usage
-
-### Installation
-
-```bash
-npm i @ticatec/batch-data-uploader
-```
-
-### 1. Define a Template Class
-
-Extend `BaseTemplate`, provide field definitions and upload logic, and optionally override `consolidateData` to process data.
-
-```ts
-import BaseUploadTemplate from '@ticatec/batch-data-uploader/BaseUploadTemplate';
-import type DataColumn from '@ticatec/batch-data-uploader/DataColumn';
-
-class MyDataTemplate extends BaseUploadTemplate {
-  constructor(uploadFun: UploadFun) {
-    const columns: DataColumn[] = [
-      { text: 'Name', field: 'name', pos: 0 },
-      { text: 'Email', field: 'email', pos: 1 },
-      { text: 'Age', field: 'age', pos: 2, parser: val => parseInt(val) },
-    ];
-    super(columns, uploadFun, 50);
-  }
-
-  // Optional: Override to implement merge/group logic
-  protected consolidateData(rows: Array<any>) {
-    return super.consolidateData(rows);
-  }
-}
-```
+## ✨ Features
 
-### 2. Use the Upload Dialog Component
-
-```svelte
-<script lang="ts">
-  import UploadDialog from './UploadDialog.svelte';
-  import { MyDataTemplate } from './MyDataTemplate';
-
-  let showDialog = false;
-
-  function doUpload(rows: any[]): Promise<void> {
-    const dataChunk = rows.map(row => row.data);
-    return fetch('/api/upload', {
-      method: 'POST',
-      body: JSON.stringify(dataChunk),
-    }).then(res => {
-      if (!res.ok) throw new Error('Upload failed');
-      // After upload, write result info to row.error if needed
-    });
-  }
-
-  const template = new MyDataTemplate(doUpload);
-  
-  const showUploadDialog = () => {
-    window.Dialog.showModal(UploadDialog, {
-      title: 'Batch Add Employees',
-      template,
-    });
-  }
-</script>
-
-<button on:click={() => showUploadDialog()}>Import Data</button>
-```
+- 📂 Supports drag-and-drop and file selection for uploading `.xlsx` files
+- 🧠 Local parsing of Excel data without server preprocessing
+- 🧩 Supports field mapping and custom parsers
+- 📝 Data preview and validation with highlighted error prompts
+- 🌐 Multilingual support (built-in Chinese and English)
+- 🔌 Compatible with the UI element style of `@ticatec/uniface-element`
 
 ---
 
-## Parameter Reference
-
-### `BaseTemplate` Constructor Parameters
-
-| Name        | Type                            | Description                                  |
-| ----------- | ------------------------------- | -------------------------------------------- |
-| `columns`   | `DataColumn[]`                  | Defines column position and format           |
-| `uploadFun` | `(arr: any[]) => Promise<void>` | Upload function, called in batches           |
-| `batchSize` | `number` (default: 50)          | Number of rows per upload batch              |
-| `rowOffset` | `number` (default: 1)           | Row offset for data start (e.g. skip header) |
+## 📦 Installation
 
-### `DataColumn` Interface
-
-```ts
-interface DataColumn {
-  text: string;                // Column display text
-  field: string;               // Data field path (supports nesting)
-  pos: number;                 // Excel column index (starting from 0)
-  parser?: (val: any) => any;  // Optional parser function for cell values
-}
+```bash
+npm install @ticatec/batch-data-uploader xlsx
 ```
 
 ---
 
-## Upload Workflow
+## 📁 Project Structure
 
-1. User selects an Excel file
-2. Call `BaseTemplate.parseExcelFile(file)` to parse data
-3. Display preview data table with `Pending` status
-4. User clicks upload, system calls `uploadFun` in batches
-5. Mark successful items, retain `error` info for failed items
-6. Failed rows can be exported to Excel
+The main components and classes are as follows:
 
----
-
-## Exporting Error Data
-
-Use `BaseTemplate.exportErrorRowsToExcel(filename: string)` to export rows with errors as an Excel file, including original columns and error messages.
+| File                       | Description                                            |
+| -------------------------- | ----------------------------------------------------- |
+| `FileUploadWizard.svelte`  | Main upload dialog, uses `BaseUploadTemplate` to upload and validate data |
+| `EncodingWizard.svelte`   | Field mapping dialog, uses `BaseEncodingTemplate` to map Excel fields |
+| `BaseTemplate.ts`         | Abstract base class encapsulating Excel parsing and column definition logic |
+| `BaseUploadTemplate.ts`   | Upload template base class for validation, preprocessing, and data uploading |
+| `BaseEncodingTemplate.ts` | Encoding template base class for dynamic field mapping and transformation |
+| `utils.ts`                | Utility functions, such as `setNestedValue` and `getNestedValue` |
+| `i18n_resources`          | Multilingual resource definitions, supporting Chinese and English switching |
 
 ---
 
-## Customization Options
-
-* **Custom Column Display**: Define column fields and formatting functions
-* **Custom Status Field**: Built-in `status` column, can be customized per business needs
-* **Data Cleaning & Validation**: Implement in `consolidateData()` method
-* **Multilingual Text**: Use `getI18nText` from `@ticatec/i18n`
+## 🚀 Usage
+
+### Batch Data Upload
+
+[Implementing Batch Data Upload](./documents/FileUploadWizard.md)
+
+### Data Parsing and Validation
+
+[Implementing Data Parsing and Validation](./documents/EncodingWizard.md)
+
+## 🌐 Multilingual Support
+
+By leveraging `@ticatec/i18n` and `i18n_resources`, automatic switching between Chinese and English is supported. You can customize internationalization by extending `i18nKeys` and resource files.
+
+English resource file, loadable via i18n tools:
+
+```json
+{
+    "batchUploading": {
+        "status": {
+            "pending": "To upload",
+            "uploading": "Uploading...",
+            "successful": "Success",
+            "fail": "Failure"
+        },
+        "parsing": "Parsing file...",
+        "parseFailure": "Cannot parse file: {{name}}",
+        "waitUploading": "Cannot exit during uploading!",
+        "button": {
+            "upload": "Upload",
+            "save": "Save error data",
+            "open": "Open",
+            "confirm": "Confirm"
+        },
+        "errorTitle": "Error",
+        "sheetName": "Abnormal data",
+        "labelStatus": "Status",
+        "labelValid": "Validity",
+        "textValid": "Yes",
+        "textInvalid": "No"
+    }
+}
+```
 
 ---
 
-## Dependencies
+## 🧪 Examples
 
-* [`xlsx`](https://www.npmjs.com/package/xlsx)
-* [`@ticatec/uniface-element`](https://www.npmjs.com/package/@ticatec/uniface-element)
-* [`@ticatec/i18n`](https://www.npmjs.com/package/@ticatec/i18n)
+Refer to the `src/routes/+page.svelte` example page for a complete usage flow and template definitions.
 
 ---
 
-## License
+## 🪪 License
 
-MIT License.
+MIT License © Ticatec
 
 ---
 
 ## Author
 
-Henry Feng
-[huili.f@gmail.com](mailto:huili.f@gmail.com)
+Henry Feng  
+huili.f@gmail.com

package/dist/BaseEncodingTemplate.d.ts

@@ -0,0 +1,30 @@
+import BaseTemplate from "./BaseTemplate";
+import type DataColumn from "./DataColumn";
+import type { DataColumn as TableColumn } from "@ticatec/uniface-element/DataTable";
+export default abstract class BaseEncodingTemplate extends BaseTemplate {
+    private validColumn;
+    protected constructor(columns: Array<DataColumn>, rowOffset?: number);
+    /**
+     * 检查一行的数据是否合法
+     * @param row
+     * @protected
+     */
+    protected abstract isDataValid(row: any): boolean;
+    /**
+     *
+     * @param rows
+     * @protected
+     */
+    protected abstract encodeData(rows: Array<any>): Promise<Array<any>>;
+    /**
+     * 数据集是否有效
+     */
+    abstract get valid(): boolean;
+    /**
+     * 从服务器抓取数据，然后根据主键进行数据合并
+     * @param rows
+     * @protected
+     */
+    protected consolidateData(rows: Array<any>): Promise<Array<any>>;
+    get columns(): Array<TableColumn>;
+}

package/dist/BaseEncodingTemplate.js

@@ -0,0 +1,34 @@
+import BaseTemplate from "./BaseTemplate";
+import { getI18nText } from "@ticatec/i18n";
+import i18nKeys from "./i18n_resources/i18nKeys";
+const ValidData = `<span style="color: #76FF03">${getI18nText(i18nKeys.textValid)}</span>`;
+const InvalidData = `<span style="color: #ff3e00">${getI18nText(i18nKeys.textInvalid)}</span>`;
+export default class BaseEncodingTemplate extends BaseTemplate {
+    validColumn = {
+        text: getI18nText(i18nKeys.labelValid),
+        width: 90,
+        align: 'center',
+        escapeHTML: true,
+        formatter: row => this.isDataValid(row) ? ValidData : InvalidData
+    };
+    constructor(columns, rowOffset = 1) {
+        super(columns, rowOffset);
+    }
+    /**
+     * 从服务器抓取数据，然后根据主键进行数据合并
+     * @param rows
+     * @protected
+     */
+    async consolidateData(rows) {
+        let list = await this.encodeData(this.extractData(rows));
+        rows.forEach((item, idx) => {
+            if (list[idx]) {
+                rows[idx] = { ...item, ...list[idx] };
+            }
+        });
+        return rows;
+    }
+    get columns() {
+        return [...this._columns, this.validColumn];
+    }
+}

package/dist/BaseTemplate.d.ts

@@ -22,6 +22,11 @@ export default abstract class BaseTemplate {
      * @param file
      */
     parseExcelFile(file: File): Promise<void>;
+    /**
+     * 获取实际待上传的数据
+     * @param arr
+     */
+    protected extractData(arr: Array<any>): any[];
     /**
      * 包裹数据
      * @param data

package/dist/BaseTemplate.js

@@ -34,8 +34,9 @@ export default class BaseTemplate {
         const rows = [];
         for (let rowIndex = range.s.r + this.rowOffset; rowIndex <= range.e.r; rowIndex++) {
             const rowObject = {};
-            for (const colDef of this._columns) {
-                const cellAddress = { r: rowIndex, c: colDef.pos };
+            for (let i = 0; i < this._columns.length; i++) {
+                const colDef = this._columns[i];
+                const cellAddress = { r: rowIndex, c: i };
                 const cellRef = XLSX.utils.encode_cell(cellAddress);
                 const cell = sheet[cellRef];
                 const rawValue = cell?.v;
@@ -46,6 +47,22 @@ export default class BaseTemplate {
         }
         this._list = await this.consolidateData(rows);
     }
+    /**
+     * 获取实际待上传的数据
+     * @param arr
+     */
+    extractData(arr) {
+        let list = arr.map(item => {
+            let result = {};
+            for (let col of this._columns) {
+                if (col.visible != false && col.ignore != false) {
+                    utils.setNestedValue(result, col.field, utils.getNestedValue(item.data, col.field));
+                }
+            }
+            return result;
+        });
+        return list;
+    }
     /**
      * 包裹数据
      * @param data

package/dist/BaseUploadTemplate.d.ts

@@ -1,18 +1,18 @@
 import BaseTemplate from "./BaseTemplate";
 import type { DataColumn as TableColumn } from "@ticatec/uniface-element/DataTable";
 import type DataColumn from "./DataColumn";
-export type UploadFun = (arr: Array<any>) => Promise<void>;
+export type UploadFun = (arr: Array<any>) => Promise<Array<any>>;
 export type UpdateProgressStatus = () => void;
 export default abstract class BaseUploadTemplate extends BaseTemplate {
-    protected uploadFun: UploadFun;
     protected batchSize: number;
     protected updateProgressStatus: UpdateProgressStatus | null;
-    protected constructor(columns: Array<DataColumn>, uploadFun: UploadFun, batchSize?: number, rowOffset?: number);
+    protected constructor(columns: Array<DataColumn>, batchSize?: number, rowOffset?: number);
     /**
      * 状态更新的监听器
      * @param value
      */
     setProgressStatusListener(value: UpdateProgressStatus): void;
+    protected abstract uploadData(list: Array<any>): Promise<Array<any>>;
     /**
      * 上传数据
      */

package/dist/BaseUploadTemplate.js

@@ -4,8 +4,8 @@ import i18nKeys from "./i18n_resources/i18nKeys";
 import utils from "./utils";
 import * as XLSX from 'xlsx';
 const statusColumn = {
-    text: "status",
-    width: 150,
+    text: getI18nText(i18nKeys.labelStatus),
+    width: 240,
     resizable: true,
     formatter: row => {
         if (row.status == 'P') {
@@ -25,13 +25,10 @@ const statusColumn = {
     }
 };
 export default class BaseUploadTemplate extends BaseTemplate {
-    uploadFun;
     batchSize;
     updateProgressStatus = null;
-    constructor(columns, uploadFun, batchSize = 50, rowOffset = 1) {
+    constructor(columns, batchSize = 50, rowOffset = 1) {
         super(columns, rowOffset);
-        ;
-        this.uploadFun = uploadFun;
         this.batchSize = batchSize;
     }
     /**
@@ -45,12 +42,20 @@ export default class BaseUploadTemplate extends BaseTemplate {
      * 上传数据
      */
     async upload() {
-        for (let i = 0; i < this.list.length; i += this.batchSize) {
-            const chunk = this.list.slice(i, i + this.batchSize);
+        for (let i = 0; i < this._list.length; i += this.batchSize) {
+            const chunk = this._list.slice(i, i + this.batchSize);
             chunk.forEach(item => item.status = 'U');
             this.updateProgressStatus?.();
-            await this.uploadFun(chunk);
-            chunk.forEach(item => item.status = 'D');
+            let list = await this.uploadData(this.extractData(chunk));
+            for (let j = 0; j < chunk.length; j++) {
+                this._list[i + j].status = 'D';
+                if (list[j]) {
+                    if (list[j].error) {
+                        this._list[i + j].error = list[j].error;
+                        this._list[i + j].errorText = list[j].errorText;
+                    }
+                }
+            }
             this.updateProgressStatus?.();
         }
     }

package/dist/DataColumn.d.ts

@@ -2,13 +2,13 @@ import type { DataColumn as TableColumn } from "@ticatec/uniface-element/DataTab
 export type ParserText = (text: string) => any;
 export default interface DataColumn extends TableColumn {
     /**
-     * 在excel中的列号
+     * 字段名
      */
-    pos: number;
+    field: string;
     /**
-     * 对于的字段名
+     * 是否忽略，上传的时候不采用，仅用于前台显示
      */
-    field: string;
+    ignore?: boolean;
     /**
      * 解析函数
      */

package/dist/EncodingWizard.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+    import Dialog from "@ticatec/uniface-element/Dialog";
+    import type {ButtonAction, ButtonActions} from "@ticatec/uniface-element/ActionBar";
+    import DataTable, {type IndicatorColumn} from "@ticatec/uniface-element/DataTable";
+    import {getI18nText} from "@ticatec/i18n";
+    import Box from "@ticatec/uniface-element/Box"
+    import {onMount} from "svelte";
+    import type DataColumn from "./DataColumn";
+    import i18nKeys from "./i18n_resources/i18nKeys";
+    import type BaseEncodingTemplate from "./BaseEncodingTemplate";
+
+    export let title: string;
+    export let width: string = "800px";
+    export let height: string = "600px"
+    export let closeHandler: any;
+    export let template: BaseEncodingTemplate;
+    export let confirmCallback: any;
+
+
+    const btnChoose: ButtonAction = {
+        label: getI18nText(i18nKeys.button.open),
+        type: 'primary',
+        handler: () => {
+            uploadField.value = '';
+            uploadField.click();
+        }
+    }
+
+    const btnConfirm: ButtonAction = {
+        label: getI18nText(i18nKeys.button.confirm),
+        type: 'primary',
+        handler: ()=> {
+            confirmCallback?.(template.list);
+            closeHandler?.();
+        }
+    }
+
+    let actions: ButtonActions = [btnChoose];
+    let uploadField: any;
+    let list: Array<any> = [];
+    let filename: string;
+
+    const parseExcelFile = async (excelFile: File) => {
+        if (excelFile) {
+            filename = excelFile.name;
+            window.Indicator.show(getI18nText(i18nKeys.parsing));
+            try {
+                await template.parseExcelFile(excelFile);
+                list = template.list;
+                if (template.valid) {
+                    actions = [btnConfirm, ...actions]
+                }
+            } catch (ex) {
+                window.Toast.show(getI18nText(i18nKeys.parseFailure, {name: excelFile.name}));
+            } finally {
+                window.Indicator.hide();
+            }
+        }
+    }
+
+
+    let columns: Array<DataColumn>;
+
+    onMount(async () => {
+        columns = template.columns;
+    });
+
+
+    const indicatorColumn: IndicatorColumn = {
+        width: 40,
+        selectable: false,
+        displayNo: true
+    }
+
+
+</script>
+
+<Dialog {title} {closeHandler} {actions}
+        content$style="width: {width}; height: {height}; padding: 12px;">
+    <Box style="border: 1px solid var(--uniface-editor-border-color, #F8FAFC); width: 100%; height: 100%; "
+         round>
+        <DataTable style="width: 100%; height: 100%" {list} {indicatorColumn} {columns}>
+
+        </DataTable>
+    </Box>
+    <input type="file" bind:this={uploadField} on:change={(e) => parseExcelFile(e.target.files?.[0])} style="display: none"
+           accept=".xls,.xlsx,application/vnd.ms-excel,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet">
+
+</Dialog>

package/dist/EncodingWizard.svelte.d.ts

@@ -0,0 +1,26 @@
+import type BaseEncodingTemplate from "./BaseEncodingTemplate";
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: Props & {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const EncodingWizard: $$__sveltets_2_IsomorphicComponent<{
+    title: string;
+    width?: string;
+    height?: string;
+    closeHandler: any;
+    template: BaseEncodingTemplate;
+    confirmCallback: any;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type EncodingWizard = InstanceType<typeof EncodingWizard>;
+export default EncodingWizard;

package/dist/FileUploadWizard.svelte

@@ -2,21 +2,19 @@
     import Dialog from "@ticatec/uniface-element/Dialog";
     import type {ButtonAction, ButtonActions} from "@ticatec/uniface-element/ActionBar";
     import DataTable, {type IndicatorColumn} from "@ticatec/uniface-element/DataTable";
-    import i18n, {getI18nText} from "@ticatec/i18n";
+    import {getI18nText} from "@ticatec/i18n";
     import Box from "@ticatec/uniface-element/Box"
     import {onMount} from "svelte";
-    import type BaseTemplate from "./BaseTemplate";
-    import type DataColumn from "@ticatec/uniface-element/DataTable";
+    import type DataColumn from "./DataColumn";
     import i18nKeys from "./i18n_resources/i18nKeys";
     import type BaseUploadTemplate from "./BaseUploadTemplate.js";
 
     export let title: string;
-
     export let width: string = "800px";
     export let height: string = "600px"
-
     export let closeHandler: any;
     export let template: BaseUploadTemplate;
+    export let afterUploaded: ()=>Promise<void>;
 
     type ProcessStatus = 'Init' | 'Pending' | 'Uploading' | 'Done';  //初始状态，待上传，上传中，处理完成
 
@@ -27,6 +25,7 @@
         label: getI18nText(i18nKeys.button.open),
         type: 'primary',
         handler: () => {
+            uploadField.value = '';
             uploadField.click();
         }
     }
@@ -38,6 +37,7 @@
             status = 'Uploading';
             try {
                 await template.upload();
+                await afterUploaded?.();
             } finally {
                 status = 'Done';
             }
@@ -58,16 +58,18 @@
     let filename: string;
 
     const parseExcelFile = async (excelFile: File) => {
-        filename = excelFile.name;
-        window.Indicator.show(getI18nText(i18nKeys.parsing));
-        try {
-            await template.parseExcelFile(excelFile);
-            list = template.list;
-            status = list.length > 0 ? 'Pending' : 'Init';
-        } catch (ex) {
-            window.Toast.show(getI18nText(i18nKeys.parseFailure, {name: excelFile.name}));
-        } finally {
-            window.Indicator.hide();
+        if (excelFile) {
+            filename = excelFile.name;
+            window.Indicator.show(getI18nText(i18nKeys.parsing));
+            try {
+                await template.parseExcelFile(excelFile);
+                list = template.list;
+                status = list.length > 0 ? 'Pending' : 'Init';
+            } catch (ex) {
+                window.Toast.show(getI18nText(i18nKeys.parseFailure, {name: excelFile.name}));
+            } finally {
+                window.Indicator.hide();
+            }
         }
     }
 
@@ -84,7 +86,7 @@
 
 
     const indicatorColumn: IndicatorColumn = {
-        width: 60,
+        width: 40,
         selectable: false,
         displayNo: true
     }

package/dist/FileUploadWizard.svelte.d.ts

@@ -18,6 +18,7 @@ declare const FileUploadWizard: $$__sveltets_2_IsomorphicComponent<{
     height?: string;
     closeHandler: any;
     template: BaseUploadTemplate;
+    afterUploaded: () => Promise<void>;
 }, {
     [evt: string]: CustomEvent<any>;
 }, {}, {}, string>;

package/dist/i18n_resources/batch_cn_resource.d.ts

@@ -16,6 +16,7 @@ declare const langRes: {
         };
         errorTitle: string;
         sheetName: string;
+        labelStatus: string;
     };
 };
 export default langRes;

package/dist/i18n_resources/batch_cn_resource.js

@@ -15,7 +15,8 @@ const langRes = {
             open: '文件'
         },
         errorTitle: '异常原因',
-        sheetName: '错误数据'
+        sheetName: '错误数据',
+        labelStatus: "状态"
     }
 };
 export default langRes;

package/dist/i18n_resources/batch_en_resource.d.ts

@@ -13,9 +13,14 @@ declare const langRes: {
             upload: string;
             save: string;
             open: string;
+            confirm: string;
         };
         errorTitle: string;
         sheetName: string;
+        labelStatus: string;
+        labelValid: string;
+        textValid: string;
+        textInvalid: string;
     };
 };
 export default langRes;