@ticatec/batch-data-uploader 0.0.3 → 0.0.9

package/documents/EncodingWizard_cn.md

@@ -0,0 +1,90 @@
+
+# Excel Encoding Wizard 组件
+
+一个基于 Svelte 的对话框组件，用于解析 Excel 文件、通过服务器端接口验证/补全数据，并显示验证结果，结合 `BaseEncodingTemplate` 实现数据处理功能。
+
+## 概述
+
+该组件提供了一个交互式的对话框界面，允许用户选择 Excel 文件、解析文件内容、通过服务器端接口验证和补全数据、显示数据表格，并在数据有效时提供确认操作。组件支持国际化、动态按钮操作，适用于需要验证和补全 Excel 数据的场景。
+
+## 使用方法
+
+将组件嵌入 Svelte 应用，并传递必要的属性。以下是一个示例：
+
+1. 实现数据模版，定义和excel文件匹配的字段。[BaseEncodingTemplate](./BaseEncodingTemplate_cn.md)
+2. 打开对话框，加载本地的excel文件，将触发解析和调用服务api验证数据，验证通过后，显示确认按钮。点击确认按钮会通过回传函数返回数据集。
+
+```typescript
+<script lang="ts">
+    import EncodingDialog from '@ticatec/batch-data-uploader/EncodingDialog.svelte';
+    import type { DataColumn } from '@ticatec/batch-data-uploader/DataColumn';
+    import MyEncodingTemplate from './MyEncodingTemplate'; // 继承自 BaseEncodingTemplate
+
+    const template = new MyEncodingTemplate();
+
+    function handleClose() {
+        console.log('Dialog closed');
+    }
+
+    function handleConfirm(data: any[]) {
+        console.log('Confirmed data:', data);
+    }
+</script>
+
+<ExcelEncodingDialog
+    title="验证 Excel 数据"
+    width="800px"
+    height="600px"
+    {template}
+    closeHandler={handleClose}
+    confirmCallback={handleConfirm}
+/>
+```
+
+## 组件详情
+
+### 属性
+
+- **title**: `string`
+    - 对话框标题。
+- **width**: `string` (默认: `"800px"`)
+    - 对话框宽度。
+- **height**: `string` (默认: `"600px"`)
+    - 对话框高度。
+- **template**: `BaseEncodingTemplate`
+    - `BaseEncodingTemplate` 实例，用于解析 Excel 文件、验证和补全数据。
+- **confirmCallback**: `any`
+    - 确认按钮点击时调用的回调函数，接收解析后的数据列表（`template.list`）。
+
+### 按钮操作
+
+- **btnChoose**: 选择文件按钮，触发文件输入框以选择 Excel 文件。
+- **btnConfirm**: 确认按钮，仅在数据有效（`template.valid` 为 `true`）时显示，调用 `confirmCallback` 并关闭对话框。
+
+### 事件处理
+
+- **文件选择**：通过隐藏的 `<input type="file">` 元素触发 `parseExcelFile`，解析选中的 Excel 文件并调用 `template.parseExcelFile` 进行验证/补全。
+- **数据验证**：解析完成后检查 `template.valid`，如果数据有效，则添加“确认”按钮。
+- **错误提示**：解析失败时通过 `window.Toast` 显示错误信息，并隐藏加载指示器。
+
+## 类型
+
+- **DataColumn**: 自定义接口，定义列元数据（继承自 `@ticatec/uniface-element/DataTable` 的 `TableColumn`）。
+- **ButtonAction** / **ButtonActions**: 来自 `@ticatec/uniface-element/ActionBar`，定义按钮操作。
+- **IndicatorColumn**: 来自 `@ticatec/uniface-element/DataTable`，定义行号列。
+
+## 依赖组件
+
+- **Dialog**: 来自 `@ticatec/uniface-element/Dialog`，提供对话框容器。
+- **DataTable**: 来自 `@ticatec/uniface-element/DataTable`，显示数据表格。
+- **Box**: 来自 `@ticatec/uniface-element/Box`，提供带边框的容器样式。
+- **getI18nText**: 来自 `@ticatec/i18n`，用于国际化文本。
+
+## 注意事项
+
+- 确保 `BaseEncodingTemplate` 已正确实现 `isDataValid`、`encodeData` 方法和 `valid` 属性，以支持数据验证和补全。
+- 文件输入框仅接受 `.xls` 和 `.xlsx` 格式的文件。
+- 解析过程中会显示加载指示器（`window.Indicator`），失败时通过 `window.Toast` 显示错误提示。
+- 确认按钮仅在 `template.valid` 为 `true` 时显示，确保只有有效数据可以提交。
+- 依赖 `window.Indicator` 和 `window.Toast` 进行 UI 提示，需确保这些全局对象已定义。
+- `confirmCallback` 接收解析后的完整数据列表，适合用于后续处理或提交。

package/documents/FileUploadWizard.md

@@ -0,0 +1,91 @@
+# FileUploadWizard Component
+
+A Svelte-based dialog component for handling Excel file uploads, parsing, and data display, integrated with `BaseUploadTemplate` to enable file parsing and batch upload functionality.
+
+## Overview
+
+This component provides an interactive dialog interface that allows users to select an Excel file, parse its contents, display a data table, perform upload operations, and export data containing errors. The component supports internationalization, dynamic button operations, and upload progress management, making it suitable for scenarios requiring batch processing of Excel data.
+
+## Usage
+
+1. Implement a data template to define fields that match the Excel file. [BaseUploadTemplate](./BaseUploadTemplate.md)
+2. Open the dialog to load a local Excel file, which triggers parsing and displays the upload button. Clicking the upload button starts the upload process.
+3. Upon upload completion, if there are errors, a button to save error data will be displayed. Clicking this button allows downloading the error data locally.
+```typescript
+<script lang="ts">
+    import ExcelUploadDialog from './ExcelUploadDialog.svelte';
+    import type { DataColumn } from './DataColumn';
+    import MyUploadTemplate from './MyUploadTemplate'; // Extends BaseUploadTemplate
+    const template = new MyUploadTemplate();
+
+    async function handleAfterUploaded() {
+        console.log('Upload completed');
+    }
+
+    function handleClose() {
+        console.log('Dialog closed');
+    }
+</script>
+
+<ExcelUploadDialog
+    title="Upload Excel File"
+    width="800px"
+    height="600px"
+    {template}
+    afterUploaded={handleAfterUploaded}
+/>
+```
+
+## Component Details
+
+### Properties
+
+- **title**: `string`
+  - The dialog title.
+- **width**: `string` (default: `"800px"`)
+  - The dialog width.
+- **height**: `string` (default: `"600px"`)
+  - The dialog height.
+- **template**: `BaseUploadTemplate`
+  - An instance of `BaseUploadTemplate` used for parsing and uploading Excel data.
+- **afterUploaded**: `() => Promise<void>`
+  - A callback function invoked after the upload is completed.
+
+### Button Actions
+
+- **btnChoose**: File selection button that triggers the file input dialog.
+- **btnUpload**: Upload button that calls `template.upload()` to perform batch uploads.
+- **btnSave**: Save errors button that calls `template.exportErrorRowsToExcel()` to export data with errors.
+
+### Event Handling
+
+- **File Selection**: Triggered via a hidden `<input type="file">` element, which calls `parseExcelFile` to parse the selected Excel file.
+- **Upload Progress**: Listens to upload progress via `template.setProgressStatusListener` to dynamically update `list`.
+- **Close Confirmation**: Uses `confirmCloseDialog` to prevent closing the dialog during the `Uploading` state.
+
+### Component Logic
+
+- **Initialization**: In `onMount`, retrieves `template.columns` and sets the progress status listener.
+- **Status Management**: Dynamically updates button states and availability based on `status`:
+  - `Init`: Displays only the "Choose File" button.
+  - `Pending`: Displays "Upload" and "Choose File" buttons.
+  - `Uploading`: Disables all buttons and changes the mouse cursor to a loading state.
+  - `Done`: If error data exists, displays "Save Errors" and "Choose File" buttons; otherwise, displays only the "Choose File" button.
+- **File Parsing**: Calls `template.parseExcelFile` to parse the Excel file, displays a loading indicator, and handles success or failure prompts.
+- **Data Table**: Uses the `DataTable` component to display parsed data, including an indicator column (showing row numbers).
+
+## Types
+
+- **ProcessStatus**: `'Init' | 'Pending' | 'Uploading' | 'Done'`
+  - Represents the data processing status.
+- **DataColumn**: A custom interface defining column metadata (extends `TableColumn` from `@ticatec/uniface-element/DataTable`).
+- **ButtonAction** / **ButtonActions**: From `@ticatec/uniface-element/ActionBar`, defining button operations.
+- **IndicatorColumn**: From `@ticatec/uniface-element/DataTable`, defining the row number column.
+
+## Notes
+
+- Ensure `BaseUploadTemplate` correctly implements the `uploadData` method to handle the actual upload logic.
+- The file input only accepts `.xls` and `.xlsx` file formats.
+- A loading indicator is displayed during the upload process, and errors are shown via `window.Toast`.
+- The dialog checks for the `Uploading` state when closing to prevent interrupting the upload.
+- The exported error data filename is formatted as `error-${filename}`, based on the original filename.

package/documents/FileUploadWizard_cn.md

@@ -0,0 +1,94 @@
+
+# FileUploadWizard 组件
+
+一个基于 Svelte 的对话框组件，用于处理 Excel 文件的上传、解析和数据显示，结合 `BaseUploadTemplate` 实现文件解析和批量上传功能。
+
+## 概述
+
+该组件提供了一个交互式的对话框界面，允许用户选择 Excel 文件、解析文件内容、显示数据表格、执行上传操作，并支持导出包含错误的数据。组件支持国际化、动态按钮操作和上传进度管理，适用于需要批量处理 Excel 数据的场景。
+
+## 使用方法
+
+1. 实现数据模版，定义和excel文件匹配的字段。[BaseUploadTemplate](./BaseUploadTemplate_cn.md)
+2. 打开对话框，加载本地的excel文件，将触发解析，显示上传按钮。点击上传按钮会开始上传过程。
+3. 上传完毕，如果有错误将显示保存错误数据的按钮，点击按钮可以将错误数据下载到本地
+
+```typescript
+<script lang="ts">
+    import ExcelUploadDialog from './ExcelUploadDialog.svelte';
+    import type { DataColumn } from './DataColumn';
+    import MyUploadTemplate from './MyUploadTemplate'; // 继承自 BaseUploadTemplate
+    const template = new MyUploadTemplate();
+
+    async function handleAfterUploaded() {
+        console.log('Upload completed');
+    }
+
+    function handleClose() {
+        console.log('Dialog closed');
+    }
+</script>
+
+<ExcelUploadDialog
+    title="上传 Excel 文件"
+    width="800px"
+    height="600px"
+    {template}
+    afterUploaded={handleAfterUploaded}
+/>
+```
+
+## 组件详情
+
+### 属性
+
+- **title**: `string`
+    - 对话框标题。
+- **width**: `string` (默认: `"800px"`)
+    - 对话框宽度。
+- **height**: `string` (默认: `"600px"`)
+    - 对话框高度。
+- **template**: `BaseUploadTemplate`
+    - `BaseUploadTemplate` 实例，用于解析和上传 Excel 数据。
+- **afterUploaded**: `() => Promise<void>`
+    - 上传完成后的回调函数。
+
+### 按钮操作
+
+- **btnChoose**: 选择文件按钮，触发文件输入框。
+- **btnUpload**: 上传按钮，调用 `template.upload()` 执行批量上传。
+- **btnSave**: 保存错误按钮，调用 `template.exportErrorRowsToExcel()` 导出包含错误的数据。
+
+### 事件处理
+
+- **文件选择**：通过隐藏的 `<input type="file">` 元素触发 `parseExcelFile`，解析选中的 Excel 文件。
+- **上传进度**：通过 `template.setProgressStatusListener` 监听上传进度，动态更新 `list`。
+- **关闭确认**：通过 `confirmCloseDialog` 阻止在上传中 (`Uploading`) 关闭对话框。
+
+### 组件逻辑
+
+- **初始化**：在 `onMount` 中获取 `template.columns` 并设置进度状态监听器。
+- **状态管理**：根据 `status` 动态更新按钮状态和可用性：
+    - `Init`: 仅显示“选择文件”按钮。
+    - `Pending`: 显示“上传”和“选择文件”按钮。
+    - `Uploading`: 禁用所有按钮，鼠标指针变为加载状态。
+    - `Done`: 如果存在错误数据，显示“保存错误”和“选择文件”按钮；否则仅显示“选择文件”按钮。
+- **文件解析**：调用 `template.parseExcelFile` 解析 Excel 文件，显示加载指示器，处理成功或失败的提示。
+- **数据表格**：使用 `DataTable` 组件显示解析后的数据，包含一个指示列（显示行号）。
+
+## 类型
+
+- **ProcessStatus**: `'Init' | 'Pending' | 'Uploading' | 'Done'`
+    - 表示数据处理的状态。
+- **DataColumn**: 自定义接口，定义列元数据（继承自 `@ticatec/uniface-element/DataTable` 的 `TableColumn`）。
+- **ButtonAction** / **ButtonActions**: 来自 `@ticatec/uniface-element/ActionBar`，定义按钮操作。
+- **IndicatorColumn**: 来自 `@ticatec/uniface-element/DataTable`，定义行号列。
+
+## 注意事项
+
+- 确保 `BaseUploadTemplate` 已正确实现 `uploadData` 方法，以处理实际的上传逻辑。
+- 文件输入框仅接受 `.xls` 和 `.xlsx` 格式的文件。
+- 上传过程中会显示加载指示器，失败时通过 `window.Toast` 显示错误提示。
+- 关闭对话框时会检查是否处于 `Uploading` 状态，防止中断上传。
+- 错误数据导出文件名格式为 `error-${filename}`，基于原始文件名。
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ticatec/batch-data-uploader",
-  "version": "0.0.3",
+  "version": "0.0.9",
   "description": "A reusable Svelte component for batch uploading Excel data with support for error handling, multi-language, and preprocessing.",
   "scripts": {
     "dev": "vite dev",
@@ -22,6 +22,7 @@
   ],
   "files": [
     "dist",
+    "documents",
     "!dist/**/*.scss",
     "!dist/**/*.test.*",
     "!dist/**/*.spec.*"
@@ -46,9 +47,9 @@
       "types": "./dist/BaseUploadTemplate.d.ts",
       "import": "./dist/BaseUploadTemplate.js"
     },
-    "./BaseLoadTemplate": {
-      "types": "./dist/BaseLoadTemplate.d.ts",
-      "import": "./dist/BaseLoadTemplate.js"
+    "./BaseEncodingTemplate": {
+      "types": "./dist/BaseEncodingTemplate.ts.d.ts",
+      "import": "./dist/BaseEncodingTemplate.ts.js"
     },
     "./DataColumn": {
       "types": "./dist/DataColumn.d.ts",
@@ -57,6 +58,10 @@
     "./FileUploadWizard.svelte": {
       "types": "./dist/FileUploadWizard.svelte.d.ts",
       "import": "./dist/FileUploadWizard.svelte"
+    },
+    "./EncodingWizard.svelte.svelte": {
+      "types": "./dist/EncodingWizard.svelte.d.ts",
+      "import": "./dist/EncodingWizard.svelte"
     }
   },
   "peerDependencies": {
@@ -87,5 +92,13 @@
   "private": false,
   "dependencies": {
     "xlsx": "^0.18.5"
-  }
+  },
+  "repository": {
+    "type": "https",
+    "url": "https://github.com/ticatec/batch-upload.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ticatec/batch-upload/issues"
+  },
+  "homepage": "https://github.com/ticatec/batch-upload"
 }

package/dist/BaseLoadTemplate.d.ts

@@ -1,18 +0,0 @@
-import BaseTemplate from "./BaseTemplate";
-import type DataColumn from "./DataColumn";
-export type DataFetcher = (rows: Array<any>) => Promise<Array<any>>;
-export type CheckMatch = (o1: any, o2: any) => boolean;
-/**
- * 用于前台数据和服务器端的数据整合
- */
-export default abstract class BaseLoadTemplate extends BaseTemplate {
-    protected fetcher: DataFetcher;
-    protected isMatch: CheckMatch;
-    protected constructor(columns: Array<DataColumn>, fetcher: DataFetcher, checkMatch: CheckMatch, rowOffset?: number);
-    /**
-     * 从服务器抓取数据，然后根据主键进行数据合并
-     * @param rows
-     * @protected
-     */
-    protected consolidateData(rows: Array<any>): Promise<Array<any>>;
-}

package/dist/BaseLoadTemplate.js

@@ -1,25 +0,0 @@
-import BaseTemplate from "./BaseTemplate";
-/**
- * 用于前台数据和服务器端的数据整合
- */
-export default class BaseLoadTemplate extends BaseTemplate {
-    fetcher;
-    isMatch;
-    constructor(columns, fetcher, checkMatch, rowOffset = 1) {
-        super(columns, rowOffset);
-        this.fetcher = fetcher;
-        this.isMatch = checkMatch;
-    }
-    /**
-     * 从服务器抓取数据，然后根据主键进行数据合并
-     * @param rows
-     * @protected
-     */
-    async consolidateData(rows) {
-        let data = await this.fetcher?.(rows);
-        return rows.map(row => {
-            let item = data.find(el => this.isMatch(row, el));
-            return [...row, ...item];
-        });
-    }
-}